AWS Role クラウドアカウントを作成¶
POST /api/v1/cloud_account/do/add
概要¶
現在のワークスペースの AWS assume_role 設定を作成し、独立した External ID を生成します。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。管理用の4つのエントリには cloudAccount.accountManage が必要で、無料プランでは明示的に拒否されます。アカウントスコープは Key が属するワークスペースです。一時認証情報の読み取りには別途 cloudAccount.temporaryCredentialsRead が必要で、管理権限に自動的に含まれることはありません。プラットフォーム認可は本ワークスペースのブランドおよび cn/intl パーティションに基づいて選択され、他のブランドへフォールバックしません。すべてのレスポンスには Cache-Control: no-store、Pragma: no-cache が付与されます。
まず設定を作成し、返却された 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 サイト一覧を参照してください。
認可コンテキストは自動生成され、dryRun/externalId/authorizationContext や顧客の AK/SK は受け取りません。作成時はまず同一アカウントの旧 accessKey/role との競合を確認し、その後 Account ID で重複判定します(名前では判定しません)。あいまい検索の一覧で1件もヒットしなかったことを理由に未作成と推測してはいけません。検証には、正しい External ID による1回の正常系プローブと、欠落/誤った External ID による2回の異常系プローブが含まれ、異常系プローブはいずれも明確に拒否される必要があります。検証に失敗しても isAvailable=false のまま正常に保存できる場合があり、これは AWS リソースが作成済みであることや収集サービスの権限が完全であることを示しません。
タイムアウト/5xx 後は、まず list をページングして config.accountId、area を正確に照合するか、競合時に返却された existingCloudAccountUUIDs を使用してレコードを復元します。設定の保存が確認できない場合、認可フィールドは null です。送信後の段階でエラーが発生した場合、操作エラーが併存していても creationResult.status=created となることがあるため、必ず読み戻して確認する必要があります。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Body リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| config | object | Y | 作成時は完全な設定が必須です。変更時はオブジェクトが必須で、{} は元の設定を保持しますが検証は行われ、dryRun=false の場合は既存の収集スクリプトが再同期される可能性があります。externalId/ブランド/ワークスペース/長期認証情報など未公開フィールドを追加してはいけません。 null 許容: False 例: {}取得または入力方法: 顧客の AWS アカウント/IAM ロール情報と以下のフィールドから構築します。 |
| config.accountId | string | Y | 作成時は必須で、業務要件としてちょうど12桁の数字からなる文字列です。プラットフォームアカウント ID/メールアドレス/Role ARN ではありません。変更時にアカウントの変更は受け付けません。一覧の同名 Query はあいまい絞り込みであるため、混同しないでください。 空文字列許容: True null 許容: False 例: 123456789012取得または入力方法: 顧客の AWS コンソールのアカウント情報から12桁の Account ID を取得し、先頭の 0 を保持します。 |
| config.accountName | string | Y | 作成時は必須の空でない文字列です。変更時に省略した場合は保持され、空文字列は業務バリデーションで拒否されます。最大256加重文字です。AWS のログインユーザー名や一意の Account ID ではなく、復元時の一意キーとしても使用されません。 null 許容: False 最大長: 256 例: example-account取得または入力方法: 呼び出し側が識別しやすいクラウドアカウント表示名を提供します。 |
| config.area | custom_enum | Y | 作成時は必須で cn/intl のいずれかで、それぞれ aws-cn/aws に対応します。単一の AWS Region ではありません。変更は受け付けず、元のパーティションは固定されます。現在のブランド/パーティションのプラットフォーム認可が利用できない場合は作成できません。 null 許容: False 選択可能な値: ['cn', 'intl'] 例: intl取得または入力方法: AWS 中国パーティションでは cn、グローバルパーティションでは intl を選択し、顧客アカウントおよびロール ARN のパーティションと一致させる必要があります。 |
| config.authType | custom_enum | Y | 作成時は必須で assume_role のみです。変更時に切り替えることはできず、旧 role/accessKey は使用しません。 null 許容: False 選択可能な値: ['assume_role'] 例: assume_role取得または入力方法: サードパーティの AWS IAM Role 認可方式を使用します。 |
| config.extraTags | array | 任意で最大50項目です。作成時に省略した場合は []、変更時に省略した場合は保持、[] はクリアです。各項目は key/value のみで文字列であり、追加フィールドを含めることはできません。このページはタグを管理しますが、既存の履歴テレメトリデータを直接書き換えるものではありません。 null 許容: False 最大長: 50 例: [{"key": "env", "value": "prod"}]取得または入力方法: 顧客がクラウド収集データに付加するタグのキーと値を選択します。実際の業務命名を事前に確認してください。 |
|
| config.extraTags[*] | object | 単一オブジェクトはちょうど key/value を持つ必要があり、null は不可です。重複キーは拒否され、最後の値で上書きされることはありません。 例: {"key": "env", "value": "prod"}取得または入力方法: 1組の業務タグキーと値です。 |
|
| 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 | Y | 作成時は必須で、変更時に省略した場合は保持されます。空でない ASCII のパス/名前で、arn: または / で始めることはできず、/ で終わることもできません。末尾の名前は1..64文字で、英字/数字/_+=,.@- のみ許可されます。パスは区切り文字を含めて IAM の最長512文字の規則に適合し、公開されている総長上限は575です。変更時は顧客側のロールと信頼ポリシーを同期する必要があり、表示名だけを変更することはできません。 null 許容: False 最大長: 575 例: collection/ExampleCollector取得または入力方法: 顧客の IAM ロール ARN の role/ 以降にある完全なパスとロール名から取得します。 |
| provider | custom_enum | Y | 作成時は必須で aws のみです。Front のマルチクラウドアカウント作成エントリではなく、ak/sk や他のクラウドプロバイダーを渡しません。 null 許容: False 選択可能な値: ['aws'] 例: aws取得または入力方法: 現在の公開管理エントリは AWS のみをサポートします。 |
パラメータ補足説明¶
AWS の assume_role のみをサポートします。呼び出し元は現在のワークスペースの cloudAccount.accountManage 権限を持つ必要があり、無料プランでは使用できません。DF-API-KEY を使用しますが、この権限には一時認証情報の読み取り権限は自動的に含まれません。
サードパーティ自動化による認可¶
- 設定を作成し、返却された
uuid、externalId、platformAccountIdを保存します。初回検証は失敗する可能性がありますが、設定は引き続き保存できます。HTTP 成功は AWS 認可が通過したことを意味しません。 - サードパーティは、顧客が認可済みの AWS IAM/CloudFormation 権限を使用して Role を作成し、収集に必要な読み取り権限を設定し、以下の信頼ポリシーを設定します。
cnはaws-cn、intlはawsに対応します。プラットフォームアカウント ID と External ID は、このレコードの返却値に置き換えてください。OpenAPI は顧客の AWS リソースを代行管理せず、顧客の AK/SK も受け取りません。 - Role のパス/名前は
config.roleNameと一致する必要があります。顧客のデプロイ完了後、変更インターフェース{"config":{},"dryRun":true}を呼び出して検証します。通過後にdryRun=falseを渡して再検証し、保存します。IAM の伝播遅延に対しては上限付きのバックオフを行い、External ID を重複作成したりローテーションしたりしないでください。ロールの権限ポリシーと信頼ポリシーは2つの独立した設定です。信頼が成功しただけでは、すべての収集サービスの権限が揃っていることは保証されません。 - マルチアカウント自動化では、顧客の AWS アカウントごとに UUID/External ID のマッピングを保存し、External ID を共有しないでください。クラウドアカウント管理はコレクターを自動インストールしません。
レスポンスと復元¶
creationResult.status:createdまたはfailed、validationResult.status:not_run、passedまたはfailed。それぞれcode/messageを持ちます。1回の検証には、元の正しい/欠落/誤った External ID のプローブが含まれます。- 作成成功時は
uuid、externalId、platformAccountId、isAvailableを返します。検証失敗でもcreatedとなる場合があります。作成成功が確認できない場合、認可フィールドは null で、HTTP エラー状態が 200 に変更されることはありません。 dryRun、externalId、authorizationContext、ブランドまたはワークスペースの上書きフィールドは受け取りません。作成時の External ID はプラットフォームが生成するため、追加のフロントエンド操作は不要です。- 同一ワークスペース内の同一 AWS Account ID に既存の旧
accessKey/roleがある場合、ft.CloudAccountLegacyCredentialsConflict(409)とcontent.existingCloudAccountUUIDsを返します。ユーザーが旧レコードを処理した後に再試行してください。作成時点で既に存在するレコードのみを確認し、エントリ間の恒久的/同時実行の相互排他を保証するものではありません。 - 重複作成時は
ft.CloudAccountAKRepeatの競合と既存レコードの UUID を引き続き使用し、自動変更や置換は行いません。ネットワークタイムアウト/5xx 後は、まず一覧からレコードを復元します。accountIdはあいまい検索であるため、ページを走査してconfig.accountIdを正確に照合する必要があります。レコードが見つかった場合は元の UUID/External ID を引き続き使用します。見つからない場合でも、1回の検索結果を「以前のリクエストが必ず未送信」とみなしてはいけません。上限付きで検索し、競合結果を確認してから再試行を判断してください。 - パラメータ/認証/競合などの検証前に失敗した場合は
not_runです。検証完了後にロックまたは送信に失敗した場合も、今回のpassed/failedは保持されます。5xx では安全な汎用エラーと traceId を返し、元の SQL/AWS レスポンスは返しません。
AWS リファレンス: サードパーティのクロスアカウント認可、CloudFormation Role。
リクエスト例¶
curl --request POST 'https://openapi.guance.com/api/v1/cloud_account/do/add' \
-H 'DF-API-KEY: <DF-API-KEY>' \
-H 'Content-Type: application/json' \
--data-raw '{"provider":"aws","config":{"authType":"assume_role","area":"intl","accountId":"123456789012","roleName":"collection/ExampleCollector","accountName":"example-account","extraTags":[{"key":"env","value":"prod"}]}}'
レスポンス¶
HTTP 200、application/json。以下の例は直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.uuid | string または null | 保存が確認された場合は clac_ UUID、それ以外は null。 |
| content.externalId | string または null | このレコードで生成された独立した External ID。AWS の信頼条件として設定します。保存が未確認の場合は null。 |
| content.platformAccountId | string または null | 現在のブランド/パーティションのプラットフォーム AWS Account ID。顧客の Account ID ではありません。保存が未確認の場合は null。 |
| content.isAvailable | boolean または null | 今回の検証の可用性。保存されたかどうかとは独立しています。 |
| content.creationResult | object | 作成/永続化操作の結果。 |
| content.creationResult.status | string | 操作結果の状態。creationResult または operationResult の説明に従います。 |
| content.creationResult.code | string | 操作エラーコード。成功時は空文字列です。validationResult.code とは異なります。 |
| content.creationResult.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.existingCloudAccountUUIDs | array<string> | 関連する競合エラーの content にのみ存在し、本ワークスペースで復元可能なレコード UUID です。 |
| content.existingCloudAccountUUIDs[] | string | 単一のクラウドアカウント UUID。 |
| content.declaration | object | 成功レスポンスの外層にある共通宣言。独自に返すエラーにはこの宣言は付与されません。 |
| レスポンスヘッダー | 型 | 説明 |
|---|---|---|
| Cache-Control | string | no-store。成功時およびこのブループリント経由のルーティングエラー時もキャッシュを禁止します。 |
| Pragma | string | no-cache。 |
{
"code": 200,
"content": {
"uuid": "clac_example",
"externalId": "EXTERNAL-ID-EXAMPLE",
"platformAccountId": "111111111111",
"isAvailable": false,
"creationResult": {
"status": "created",
"code": "",
"message": ""
},
"validationResult": {
"status": "failed",
"code": "ft.CloudAccountAuthInvalid",
"message": "无效账号,请检查配置信息是否正确,并确保网络连接正常"
},
"declaration": {}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-EXAMPLE"
}
顧客側の信頼ポリシー例(プラットフォームアカウント/External ID は必ずこのレコードの返却値に置き換え、cn パーティションでは ARN プレフィックスを aws-cn に置き換えてください。必要な収集読み取り権限ポリシーは別途設定します):
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111111111111:root"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "EXTERNAL-ID-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.InvalidCloudAccountType | 渡された、または対象レコードが AWS assume_role ではない | 無効なクラウドアカウントタイプ | 現在のワークスペース専用のクラウドアカウント一覧からレコードを取得します。旧 accessKey/role や他社クラウドはこのエントリでは使用できません。 |
| 400 | ft.ParamsValidateError | JSON Body が空オブジェクト {} ではない、または過去に保存された AWS assume_role 設定がアカウント/ロール/External ID の仕様に適合しない | パラメータ検証失敗: {} | リクエストでは {} のみを送信します。過去の設定が不正な場合は、権限を持つクラウドアカウント管理フローで確認・修復し、このインターフェースでは dryRun/設定更新フィールドを渡しません。 |
| 400 | ft.CloudAccountAssumeRoleCreationDisabled | 現在のブランド/パーティションのプラットフォーム認可が未開放、または情報が不完全 | 現在の環境では assume_role 認可の新規追加は未開放です。管理者に連絡してください | 管理者に連絡してこのブランド/パーティションのサポートを確認し、他のブランドのプラットフォーム ID に変更しないでください。 |
| 400 | ft.CloudAccountAuthorizationContextInvalid | サーバー側で自動生成された認可コンテキストが失効した、または ID/ブランド/設定が一致しない | 認可ドラフトが失効したか、現在の操作と一致しません。再生成してください | 現在のワークスペース/ブランドおよび同時変更を確認します。まず照会して作成済みレコードを復元し、その後ガイダンスに従って再試行します。 |
| 409 | ft.CloudAccountLegacyCredentialsConflict | 同一 AWS Account ID に旧 accessKey/role の非削除レコードが既に存在 | 現在のワークスペースにこの AWS アカウントの旧認証情報レコードが既に存在します。旧レコードを手動で削除してから再試行してください | まず existingCloudAccountUUIDs で旧収集への依存を確認し、業務認可に従って旧レコードを処理します。自動上書きは行いません。 |
| 400 | ft.CloudAccountAKRepeat | 同一ワークスペースに同じ AWS Account ID の assume_role レコードが既に存在 | 現在のワークスペースに同一の {} {} が既に存在します |
返却された existingCloudAccountUUIDs と元の External ID を引き続き使用し、アカウントを重複作成しません。 |
| 429 | ft.OperationTooFrequently | 書き込みロックの競合/ロック喪失、待機中に設定が他のリクエストによって変更された | 操作が頻繁すぎます。しばらくしてから再試行してください | 上限付きバックオフの前に UUID で読み戻し、古いスナップショットに基づいて新しい送信を上書きしないでください。作成結果が不明な場合はまず Account ID で復元します。 |
| 500 | ft.CodeError | クラウドアカウント/履歴 JSON/コレクター情報またはプラットフォーム認可表示の読み取り中に内部例外が発生 | 内部処理エラー | traceId と Query を保持し、履歴設定/データベースおよびプラットフォーム認可を確認します。この読み取りでは収集スクリプトのデプロイや設定書き込みは実行されません。 |