コンテンツにスキップ

インシデント AI 自動分析設定の一括設定



POST /api/v1/workspace/incidents/ai_analysis/batch_set

概要

インシデント AI 自動分析を一括で設定します。

呼び出し前の確認と使用手順

まずワークスペース一覧から、対象となるすべてのアクティブワークスペースを確認します。重複した UUID は 1 回のみカウントされ、返される count は重複排除後のリクエスト対象ワークスペース数であり、変更が発生したワークスペース数ではありません。本操作はインシデント AI 自動分析設定のみを設定します。ワークスペースの AI マスタースイッチは有効化されず、過去のインシデントの再実行も開始されません。AI 機能を利用する必要がある場合は、マスタースイッチとインシデント自動分析スイッチをそれぞれ確認してください。インシデント設定が存在しない場合は、対応する設定が作成されます。

リクエストヘッダー

パラメータ名 型 必須 説明
X-Df-SVersion string 例と一致させる必要があり、省略したままこのアルゴリズムを継続利用することはできません。
例: v20240417
取得または入力方法: 本ページの元のパスおよびリクエストボディの署名アルゴリズムに合わせて入力します。
X-Df-Access-Key string Y ここでは 7 項目すべてが書き込み操作であり、External の書き込み権限が必要です。
例: <external-access-key>
取得または入力方法: サイト管理者が w 権限を付与した External API AK を割り当てます。ワークスペースの OpenAPI Key ではありません。
X-Df-Nonce string Y 再送信のたびにこの値と署名も更新します。
例: 97d275ee9f774315a7885ba7347acbd9
取得または入力方法: リクエストごとに uuid.uuid4().hex を再生成します。
X-Df-Signature string Y 大文字のメソッド、nonce、元の完全なパス、timestamp、および元の UTF-8 リクエストボディをスペースで連結し、HMAC-SHA256 の hex ダイジェストを取得します。
例: <hmac-sha256-hex>
取得または入力方法: 対応する SK を使用し、External API 署名認証および下記の Python テンプレートに従って計算します。
X-Df-Timestamp string Y 例の固定時刻を再利用することはできません。サイトの署名有効ウィンドウ内である必要があります。
例: 1785427200
取得または入力方法: 送信時に str(int(time.time())) で現在の Unix 秒を生成します。

Body リクエストパラメータ

パラメータ名 型 必須 説明
workspaceUUIDs[*] string 単一のアクティブワークスペース UUID。前後の空白を除去したうえで、順序を保持した重複排除の対象になります。
例: wksp_example001
取得または入力方法: ワークスペース一覧の content.data[].uuid から項目ごとに取得します。
enableAIAnalysis boolean Y 必須の JSON ブール値。enableAI を同時に変更することはありません。
null の許可: False
例: true
取得または入力方法: 業務目的に応じて true で有効化、false で無効化します。文字列ではありません。
workspaceUUIDs array Y 必須の非空文字列配列。各項目の前後の空白を除去し、最初に出現した順序で重複を排除します。1 つでも無効なワークスペースがあると、バッチ全体がまず失敗します。アカウント UUID や収集 Token を入力しないでください。
null の許可: False
例: ["wksp_example001"]
取得または入力方法: ワークスペース一覧の content.data[].uuid から対象ワークスペースを選択します。各ワークスペースはアクティブ status=0 である必要があります。

パラメータ補足説明

w 権限を持つサイトレベルの External API 資格情報を使用します。認証方式はExternal API 署名認証を参照してください。例では v20240417 に従って署名を計算しており、署名と送信には同一のパス、Query、元のリクエストボディを使用します。すべての例はデモ用の値であり、実行前に実際の対象へ置き換えてください。書き込みリクエストがタイムアウトまたは 500 になった場合は、まず現状を照会し、確認したうえで再試行するかどうかを判断してください。インシデント設定と AI マスタースイッチは独立した機能であり、この設定を有効化しても毎回のインシデントで必ず AI 分析が実行されることは保証されません。マスタースイッチ、データ、実行条件に依存します。

リクエスト例

import hashlib
import hmac
import json
import time
import uuid
from urllib.parse import urlencode
from urllib.request import Request, urlopen

# 対象サイトのアドレスおよび管理者が割り当てた External API AK/SK に置き換えます。
server = "https://external-api.guance.com"
access_key = "<external-access-key>"
secret_key = "<external-secret-key>"
method = 'POST'
path = '/api/v1/workspace/incidents/ai_analysis/batch_set'
query = {}
data = {'workspaceUUIDs': ['wksp_example001'], 'enableAIAnalysis': True}
full_path = path + ("?" + urlencode(query) if query else "")
body = "" if data is None else json.dumps(data, ensure_ascii=False, separators=(",", ":"))
timestamp = str(int(time.time()))
nonce = uuid.uuid4().hex
string_to_sign = " ".join([method, nonce, full_path, timestamp, body])
signature = hmac.new(secret_key.encode("utf-8"), string_to_sign.encode("utf-8"), hashlib.sha256).hexdigest()
headers = {
    "X-Df-Access-Key": access_key,
    "X-Df-Timestamp": timestamp,
    "X-Df-Nonce": nonce,
    "X-Df-Signature": signature,
    "X-Df-SVersion": "v20240417",
}
if data is not None:
    headers["Content-Type"] = "application/json"
request = Request(server + full_path, data=None if data is None else body.encode("utf-8"), headers=headers, method=method)
with urlopen(request) as result:
    print(result.read().decode("utf-8"))

応答

HTTP 200、application/json、統一レスポンスエンベロープ。業務結果は content にあります。External は declaration を自動注入しません。ワークスペースオブジェクト内の declaration は、それ自体が保持するフィールドです。

フィールド 型 説明
content.workspaceUUIDs 文字列配列 空白を除去し、順序を保持して重複排除した後のアクティブワークスペース UUID。
content.count integer 重複排除後のリクエスト対象ワークスペース数であり、実際の変更数ではありません。
content.enableAIAnalysis boolean 今回すべての対象ワークスペースに設定したスイッチ値。
{
  "code": 200,
  "content": {
    "workspaceUUIDs": [
      "wksp_example001"
    ],
    "count": 1,
    "enableAIAnalysis": true
  },
  "errorCode": "",
  "message": "",
  "success": true,
  "traceId": "TRACE-EXAMPLE"
}

エラー応答

認証、レート制限、および共通リクエストエラーについては共通エラー定義を参照してください。

下表は本 API の業務バリデーションおよび確認済みの主なエラー分岐を示します。下流サービスは具体的なエラーマッピングに応じてその他の 4xx エラーを返す場合があります。通常の 5xx および未知の例外は、グローバル処理により ft.InternalServerError が返されます。書き込みリクエストでは、現在の設定とエラーの content を照らし合わせて有効化されたかどうかを判断する必要があり、HTTP ステータスのみでロールバックを推測してはいけません。

HTTP ステータス errorCode 発生条件 メッセージまたは応答説明 対処方法
406 ft.ParameterValidationFailed リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 パラメータ解析失敗 パラメータの位置、フィールド名、型、値を確認してください。
400 ft.RequestJsonFormatError リクエスト JSON の構文が無効 リクエスト JSON 形式エラー content.reason、line、column に従って JSON を修正してください。
400 ft.JsonFormatError JSON のトップレベルがオブジェクトではない 一部の json ファイル形式エラー パラメータ表に従って JSON オブジェクトを送信し、配列や null をリクエストボディ全体として送信しないでください。
400 ft.ParamsValidateError リクエストの業務バリデーションで、スイッチがブール値でない、UUID リストが空、または要素が非空文字列でないことを検出 パラメータ検証失敗: {} JSON ブール値のスイッチと非空文字列の UUID 配列を使用してください。
401 ft.WKSPNotExistOrReleased いずれかの対象ワークスペースが存在しない、削除済み、またはアクティブ status=0 でない ワークスペースが存在しない/または解放済み ワークスペース一覧を再読み込みし、バッチ全体の対象を修正してから再試行してください。
500 ft.InternalServerError データベース、キャッシュ、リソースサービス、または未処理のパラメータ変換例外 内部エラー traceId を保存して管理者に連絡してください。まず設定と下流の実際の状態を照会し、失敗レスポンスをそのまま保存されなかったと見なしたり、盲目的に重複作成やローテーションを行ったりしないでください。

フィードバック

このページは役に立ちましたか?