ワークスペース AI マスタースイッチの一括設定¶
POST /api/v1/workspace/ai_analysis/batch_set
概要¶
ワークスペースの AI マスタースイッチを一括設定します。
呼び出し前の準備と使用手順¶
まずワークスペース一覧で、対象となるすべてのアクティブなワークスペースを確認します。重複した UUID は 1 回だけカウントされ、返される count は重複排除後のリクエスト対象ワークスペース数であり、変更されたワークスペース数ではありません。この操作はワークスペースの enableAI のみを変更し、インシデント自動分析設定は変更しません。マスタースイッチをオフにしても元のインシデント設定値は保持されます。特定の機能をオフのまま維持する必要がある場合は、2 種類のスイッチを個別に管理してください。同じ値を設定しても成功しますが、実際に変更があった場合にのみ、対応する状態変更の監査が記録されます。アラート設定の更新は非同期で実行されるため、タスクのキュー投入に失敗した場合は、ログが記録されても成功が返されることがあります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| 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 から 1 件ずつ取得します。 |
|
| enableAI | boolean | Y | 必須の JSON ブール値です。enableAIAnalysis は同時に変更しません。 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 が返された場合は、まず現在の状態を照会し、確認してから再試行するかどうかを決定してください。API が成功しても、アラート経路が新しい状態を消費したことを意味しないため、実際に発生した新しいイベントと照らし合わせて検証してください。
リクエスト例¶
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/ai_analysis/batch_set'
query = {}
data = {'workspaceUUIDs': ['wksp_example001'], 'enableAI': 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.enableAI | boolean | 今回、すべての対象ワークスペースに設定するスイッチ値。 |
{
"code": 200,
"content": {
"workspaceUUIDs": [
"wksp_example001"
],
"count": 1,
"enableAI": 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 を保存して管理者に連絡します。まず設定とダウンストリームの実際の状態を照会し、失敗レスポンスを直接、保存されていないと見なしてはいけません。また、むやみに作成やローテーションを繰り返さないでください。 |