AWS Role クラウドアカウントの変更または検証¶
POST /api/v1/cloud_account/{cloud_account_uuid}/do/modify
概要¶
現在のワークスペースに保存済みの AWS assume_role 設定を検証または変更します。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。管理系4エントリポイントには cloudAccount.accountManage が必要で、無料プランでは明示的に拒否されます。アカウント範囲はキーが属するワークスペースとします。一時認証情報の読み取りには別途 cloudAccount.temporaryCredentialsRead が必要で、管理権限に自動的に含まれることはありません。プラットフォーム認可は本ワークスペースのブランドと cn/intl パーティションに応じて選択され、他のブランドへのフォールバックは行いません。すべてのレスポンスには Cache-Control: no-store、Pragma: no-cache が付与されます。
dryRun は明示必須で、config は必須です。{} を指定すると元の設定を検証します。変更できるのは accountName/roleName/extraTags のみで、省略した項目は保持され、タグを [] にするとクリアされます。accountId/area/authType/External ID の変更は受け付けず、旧 role の移行用エントリポイントではありません。
dryRun=true は実際の STS で同期的に検証し、アカウントを保存せず、収集スクリプトもデプロイしません。saved=false を返します。認可に失敗しても HTTP 200、operationResult=completed、validationResult=failed となる場合があります。dryRun=false も同様に先に検証し、その後 isAvailable=false で保存できる場合があります。saved=true は永続化処理の完了(設定が変わっていなくても再同期した場合を含む)のみを示し、検証の passed や収集の成功を意味しません。
既存のコレクターがある場合、正式保存ではスクリプトを再作成/配信します。設定が変わっていなくても再同期される場合があります。外部デプロイとデータベースはサービスをまたぐアトミックトランザクションではないため、失敗時は現在の永続化設定に従って復元/アンインストールを試みます。復元に失敗した場合は管理者による調査が必要で、すべてロールバック済みと主張することはできません。同時実行の設定変更では古いスナップショットによる上書きを拒否します。検証のみの場合は saved=false、正式処理の失敗でまだ確定できない場合は null、成功時は true です。
まず設定を作成し、uuid/externalId/platformAccountId を保存します。その後、権限を持つ顧客管理者または自動化が AWS で Role と権限ポリシーを作成し、プラットフォームアカウントを信頼し、返された一意の External ID を要求します。cn は aws-cn パーティション、intl は aws を使用します。roleName は IAM Role の実際のパスと同一である必要があります。初回で Role 未作成の場合、validationResult は failed でも creationResult は created のままで、同じレコードを使い続けて信頼を完了し、その後 modify dryRun=true で検証し、最後に false で保存します。重複作成によって External ID をローテーションすることはできません。完全な手順はOpenAPI 経由で AWS クラウドアカウントを接続、サイトのエンドポイントはOpenAPI サイト一覧を参照してください。
パスパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| cloud_account_uuid | string | Y | パス必須。削除されていない AWS assume_role レコードである必要があります。顧客の Account ID、ロール ARN、他のワークスペースの UUID は使用しません。 空文字列を許可: False 例: clac_example取得または入力方法: クラウドアカウント一覧 の content.data[].uuid、または作成成功時の content.uuid から、現在のワークスペースの clac_ レコードを取得します。 |
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
リクエストボディパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| config.authType | string | 作成時は必須で assume_role のみ。変更時は切り替え不可で、旧 role/accessKey は使用しません。 例: assume_role取得または入力方法: サードパーティの AWS IAM Role 認可方式を使用します。 |
|
| config.area | string | 作成時は必須で cn/intl。それぞれ aws-cn/aws に対応します。単一の AWS Region ではありません。変更時は受け付けず、元のパーティションは固定です。現在のブランド/パーティションでプラットフォーム認可が利用できない場合は作成できません。 例: intl取得または入力方法: AWS 中国パーティションは cn、グローバルパーティションは intl を選択し、顧客アカウントおよびロール ARN のパーティションと一致させる必要があります。 |
|
| config.accountId | string | 作成時は必須で、業務要件としてちょうど 12 桁の数字からなる文字列です。プラットフォームのアカウント ID、メールアドレス、Role ARN ではありません。変更時にアカウントの変更は受け付けません。一覧の同名 Query はあいまい絞り込みであるため、混同しないでください。 例: 123456789012取得または入力方法: 顧客の AWS コンソールのアカウント情報から 12 桁の Account ID を取得し、先頭の 0 を保持します。 |
|
| config | object | Y | 作成時は完全な設定が必須。変更時はオブジェクトが必須で、{} は元の設定を保持しますが検証は行い、dryRun=false の場合は既存の収集スクリプトを再同期する可能性があります。externalId/ブランド/ワークスペース/長期認証情報などの非公開フィールドを追加してはいけません。 null を許可: False 例: {}取得または入力方法: 顧客の AWS アカウント/IAM ロール情報と以下のフィールドから構築します。 |
| config.accountName | string | 作成時は空でない文字列が必須。変更時に省略すると保持され、空文字列は業務バリデーションで拒否されます。最大 256 文字(加重)です。AWS のログインユーザー名や一意の Account ID ではなく、復元時の一意キーとしても使用しません。 null を許可: False 最大長: 256 例: example-account取得または入力方法: 呼び出し元が識別しやすいクラウドアカウントの表示名を指定します。 |
|
| config.extraTags | array | 任意。最大 50 項目。作成時のデフォルトは []、変更時に省略すると保持され、[] でクリアされます。各項目は key/value のみで文字列とし、追加フィールドは指定できません。このページではタグを管理し、既存の履歴テレメトリデータを直接書き換えるものではありません。 null を許可: False 最大長: 50 例: [{"key": "env", "value": "prod"}]取得または入力方法: 顧客がクラウド収集データに付加するタグのキーと値を選択します。実際の業務上の命名を事前に確認してください。 |
|
| config.extraTags[*] | object | 単一オブジェクトはちょうど key/value である必要があり、null は不可です。重複キーは拒否され、最後の値で上書きされることはありません。 例: {"key": "env", "value": "prod"}取得または入力方法: 業務タグのキーと値のペアです。 |
|
| config.extraTags[*].key | string | 条件付き必須 | 必須で空でないこと。英字/数字/_ のみを許可し、最大 256 UTF-8 バイトです。__ で始まるキー、予約キー account_id/account_name は禁止です。同じ配列内で重複してはいけません。 null を許可: False 例: env取得または入力方法: 標準的な業務タグキーを指定します。 |
| config.extraTags[*].value | string | 条件付き必須 | 必須で空でない文字列。最大 1024 UTF-8 バイトです。制御文字および不正なサロゲート文字は禁止です。数値は呼び出し元が明示的に文字列へ変換する必要があります。 null を許可: False 例: prod取得または入力方法: 該当する業務タグの実際の値です。 |
| config.roleName | string | 作成時は必須。変更時に省略すると保持されます。空でない ASCII のパス/名前で、arn: または / で開始できず、/ で終了できません。末尾の名前部分は 1~64 文字で、英字/数字/_+=,.@- のみを許可します。パスは区切り文字を含めて IAM の最大 512 文字の規則に従い、公開時の総長上限は 575 です。変更時は顧客側のロールと信頼ポリシーを同期する必要があり、表示名だけを変更することはできません。 null を許可: False 最大長: 575 例: collection/ExampleCollector取得または入力方法: 顧客の IAM ロール ARN の role/ 以降にある完全なパスとロール名から取得します。 |
|
| dryRun | boolean | Y | 必須のブール値で、デフォルトはありません。true は実際に STS を呼び出しますが、クラウドアカウントを保存せず、収集スクリプトも配信しません。saved=false を返します。false は検証後に保存し(検証 failed でも保存可能)、既存の収集スクリプトを同期しますが、検証が必ず通過することを意味しません。作成時はこのパラメータを受け付けません。 null を許可: False 例: true取得または入力方法: 変更時に、検証のみなら true、正式保存なら false を明示的に選択します。 |
パラメータ補足説明¶
現在のワークスペースに保存済みの AWS assume_role レコードのみをサポートし、cloudAccount.accountManage が必要です。変更できるのは accountName、roleName、extraTags のみです。アカウント ID、パーティション、認証タイプ、External ID はこのインターフェースでは変更できません。
検証と保存¶
- 顧客の Role/信頼ポリシーの設定完了後、
{"config":{},"dryRun":true}を送信すると、saved=falseと今回の検証結果を返します。データベースへの書き込み、収集スクリプトの配信、変更監査の生成は行いません。 dryRun=falseを送信すると再検証し、既存のロジックで保存します。成功時はsaved=trueを返します。検証に失敗してもisAvailable=falseで保存できるため、HTTP 200 だけで認可成功と判断してはいけません。- 既存のコレクターは Front の既存ロジックに従って再同期されます。同じ設定で再試行しても再度配信される場合があります。アカウント設定保存の冪等性は下流の exactly-once を意味せず、dryRun の成功を後続の保存が必ず成功するという約束として扱わないでください。
- タグを省略すると保持され、
[]でクリアされます。RoleName はパスをサポートし、完全な ARN は受け付けません。通常の変更では元の External ID を保持します。
レスポンスと失敗¶
content.uuid、content.saved、content.operationResult、content.validationResult(および共通の content.declaration)を返します。2 組の結果はそれぞれ status/code/message を持ちます。操作状態は completed/failed、検証状態は not_run/passed/failed です。saved はコミットが未確認の場合は null、dryRun では明確に false、正式成功では明確に true です。検証完了後に保存/ロックが失敗しても今回の検証結論は保持され、HTTP はエラー状態を維持します。
対象外の認証タイプ、クロスワークスペース、削除済み UUID は業務変更の前に拒否され、STS、スクリプト、移行をトリガーしません。IAM の伝播遅延に対しては上限付きのバックオフを行い、元の UUID/External ID を再利用します。失敗時は現在の設定を照会して traceId を確認し、認可識別子を盲目的に変更しないでください。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/cloud_account/clac_example/do/modify' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"config":{},"dryRun":true}'
レスポンス¶
HTTP 200、application/json。以下の例は、直接読み取れる主要フィールドを示しています。
| フィールド | 型 | 説明 |
|---|---|---|
| content.uuid | string または null | 対象 UUID。対象の事前チェックに失敗した場合は null になり得ます。 |
| content.saved | boolean または null | dryRun 成功時は false、正式処理成功時は true、正式保存が未確認の場合は null。 |
| content.operationResult | object | 操作の適用結果。completed または failed。検証失敗でも completed となり得ます。 |
| content.operationResult.status | string | 操作結果のステータス。creationResult または operationResult の説明に従います。 |
| content.operationResult.code | string | 操作エラーコード。成功時は空文字列で、validationResult.code とは同一ではありません。 |
| content.operationResult.message | string | 操作エラーの説明。成功時は空文字列。 |
| content.validationResult | object | 同一の認可プローブによる独立した結果で、永続化された結論ではありません。 |
| content.validationResult.status | string | not_run は検証未完了、passed は通過済み、failed は実行済みだが未通過。 |
| content.validationResult.code | string | passed は空文字列、failed は通常 ft.CloudAccountAuthInvalid または ft.CloudAccountExternalIdTrustInvalid。 |
| content.validationResult.message | string | 安全な業務説明。AWS の生レスポンスや長期キーは返しません。 |
| content.declaration | object | 成功時のみラップされる外側の共通宣言。 |
| レスポンスヘッダー | 型 | 説明 |
|---|---|---|
| Cache-Control | string | no-store。成功時およびこのブループリントのルートエラー時はいずれもキャッシュ禁止です。 |
| Pragma | string | no-cache。 |
{
"code": 200,
"content": {
"uuid": "clac_example",
"saved": false,
"operationResult": {
"status": "completed",
"code": "",
"message": ""
},
"validationResult": {
"status": "passed",
"code": "",
"message": ""
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
エラーレスポンス¶
認証、レート制限、共通リクエストエラーについては共通エラー定義を参照してください。
公開宣言/認証レイヤーでの失敗では標準の content={} のみとなる場合があり、validationResult の出現は保証されません。管理系4エントリポイントが業務処理の適用段階に入った後、作成/変更の失敗時には安全な操作結果が含まれる場合があります。その内部の通常の 5xx は一律で 500 ft.CodeError を自ら返し、content は今回の検証状態を保持しますが、グローバルに InternalServerError へ置き換えられることはありません。一時認証情報エントリポイントでは、通常の未捕捉例外のみがグローバル 500 ft.InternalServerError になります。HTTP や success だけを見ず、操作結果、検証結果、saved、および読み戻したレコードを組み合わせて判断してください。
| HTTP ステータス | errorCode | 発生条件 | メッセージまたはレスポンスの説明 | 対処方法 |
|---|---|---|---|---|
| 406 | ft.ParameterValidationFailed | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反しています | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認してください。 |
| 400 | ft.RequestJsonFormatError | リクエスト JSON の構文が無効です | リクエスト JSON の形式エラー | content.reason、line、column に従って JSON を修正してください。 |
| 400 | ft.JsonFormatError | Body のトップレベルが JSON オブジェクトではありません | 一部の JSON ファイル形式エラー | 例に適合する JSON オブジェクトを送信してください。 |
| 403 | ft.Forbidden | 管理系4エントリポイントが無料プランワークスペースで明示的なバージョンチェックにより拒否されました | 操作権限がありません | ワークスペースのバージョンと管理権限を確認してください。対応する機能と認可を持つ対象ワークスペースに切り替えてください。 |
| 404 | ft.CloudAccountNotFound | 対象 UUID が現在のワークスペースの未削除クラウドアカウント範囲にありません | クラウドアカウントが存在しません | 現在のワークスペースの AWS Role クラウドアカウント一覧の content.data[].uuid から対象を再取得してください。この読み取りは書き込みロックを待機しません。 |
| 404 | ft.InvalidCloudAccountType | 指定されたレコードまたは対象レコードが AWS assume_role ではありません | 無効なクラウドアカウントタイプ | 現在のワークスペースの専用クラウドアカウント一覧からレコードを取得してください。旧 accessKey/role や他のクラウドベンダーはこのエントリポイントでは使用できません。 |
| 400 | ft.ParamsValidateError | JSON Body が空オブジェクト {} ではない、または履歴として保存済みの AWS assume_role 設定がアカウント/ロール/External ID の仕様に適合していません | パラメータ検証失敗: {} | リクエストでは {} のみを送信してください。履歴設定が不正な場合は、権限を持つクラウドアカウント管理フローで確認・修正し、このインターフェースで dryRun/設定更新フィールドを送信しないでください。 |
| 400 | ft.CloudAccountAKRepeat | 現在のワークスペースの他の assume_role レコードと Account ID が重複しています | 現在のワークスペースには同一の {} {} が既に存在します |
既存アカウントを確認し、他のレコードを移行/上書きしないでください。 |
| 429 | ft.OperationTooFrequently | 書き込みロックの競合/ロック消失、待機中に他のリクエストによって設定が変更された | 操作が頻繁すぎます。しばらくしてから再試行してください | 上限付きバックオフの前に UUID で読み戻し、古いスナップショットに基づいて新しいコミットを上書きしないでください。作成結果が不明な場合は、まず Account ID で復元します。 |
| 500 | ft.CodeError | クラウドアカウント/履歴 JSON/コレクター資料の読み取り、またはプラットフォーム認可表示で内部例外が発生しました | 内部処理エラー | traceId と Query を保持し、履歴設定/データベースおよびプラットフォーム認可を確認してください。この読み取りでは収集スクリプトのデプロイや設定書き込みは行いません。 |