AWS Role クラウドアカウントの取得¶
GET /api/v1/cloud_account/do/list
概要¶
現在のワークスペースにある AWS assume_role レコードと、現在のプラットフォーム認可状態をページ単位で読み取ります。
呼び出し前の準備と使用手順¶
対象ワークスペースの API Key を使用します。管理用の4つのエントリーポイントには cloudAccount.accountManage が必要で、無料プランでは明示的に拒否されます。アカウント範囲は Key が属するワークスペースです。一時認証情報の読み取りには別途 cloudAccount.temporaryCredentialsRead が必要で、管理権限に自動的に含まれることはありません。プラットフォーム認可は、このワークスペースのブランドと cn/intl パーティションに基づいて選択され、他のブランドへのフォールバックは行いません。すべてのレスポンスには Cache-Control: no-store と Pragma: no-cache が付与されます。
現在のワークスペース内の削除されていない AWS assume_role レコードのみを読み取ります。provider/authType を拡張して以前の認証情報や他社クラウドに適用することはできません。デフォルトは pageIndex=1/pageSize=10 で、更新日時(未更新の場合は作成日時)の降順です。content.data は行配列で、pageInfo はトップレベルにあり、content[] ではありません。uuid は完全一致でフィルタし、accountId/accountName はあいまい一致です。復元して書き込む場合は、ページを走査して元のフィールドを完全一致で照合する必要があります。
プラットフォーム認可が無効または情報が欠落している場合でも、レコードと External ID は保持され、platformAccountId=null、platformAuthorizationStatus=unavailable となり、他のブランドへのフォールバックは行いません。isAvailable は履歴状態であり、実際の検証には modify dryRun=true を使用します。一覧は STS の再検証もアカウントの変更も行いません。既存のコレクターインテグレーション情報を読み取るだけで、リアルタイムの収集成功を意味するものではありません。
まず設定を作成し、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 クラウドアカウントの接続、サイトの Endpoint はOpenAPI サイト一覧を参照してください。
リクエストヘッダー¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| DF-API-KEY | string | Y | ワークスペースの OpenAPI 認証情報。 例: <DF-API-KEY>取得または入力方法: 対象ワークスペースの API Key 管理から、この操作権限を持つ OpenAPI Key を取得します。 |
Query リクエストパラメータ¶
| パラメータ名 | 型 | 必須 | 説明 |
|---|---|---|---|
| accountId | string | 任意のあいまい一致です。一意にヒットすることは保証されません。作成結果を復元する場合は、ページごとに config.accountId および area/authType を完全一致で照合する必要があります。 null の許可: False 例: 123456789012取得または入力方法: 顧客の AWS アカウント情報または保存済みの config.accountId から取得します。 |
|
| accountName | string | 任意のあいまい一致です。省略時はフィルタしません。IAM ロール名ではありません。SQL のあいまい一致ワイルドカードがヒットに影響する可能性があるため、元の値を正確に確認してください。 null の許可: False 例: example-account取得または入力方法: 保存済みの config.accountName 表示名のキーワード。 |
|
| area | custom_enum | 任意。省略時はパーティションでフィルタしません。内部的には保存済み設定で比較し、ワークスペース/ブランドを切り替えません。 null の許可: False 選択可能な値: ['cn', 'intl'] 例: intl取得または入力方法: 作成レコードの config.area から cn/intl を取得します。 |
|
| pageIndex | integer | 任意。デフォルトは 1 で、常に正の整数を推奨します。公開仕様では統一された最小値が宣言されておらず、0/負数を受け入れてページングが有効になることを保証するものではありません。 null の許可: False 例: 1取得または入力方法: 呼び出し元が最初のページから走査します。 |
|
| pageSize | integer | 任意。デフォルトは 10 で、正の整数を推奨します。公開仕様では最大値が宣言されておらず、サーバー側でも統一的な上限は追加されないため、1回のリクエストが大きくなりすぎないようにしてください。 null の許可: False 例: 10取得または入力方法: クライアントの一括読み取り要件に応じて適切な数を選択します。 |
|
| uuid | string | 一覧では任意の完全一致フィルタです。指定しない場合は、現在のワークスペース内の削除されていないすべての AWS assume_role レコードを取得します。AWS Account ID/External ID ではありません。 null の許可: False 例: clac_example取得または入力方法: クラウドアカウント一覧 の content.data[].uuid または作成成功時の content.uuid から clac_ 識別子を取得します。 |
パラメータ補足説明¶
現在のワークスペースの AWS assume_role レコードのみを返します。cloudAccount.accountManage が必要で、一時認証情報の読み取り権限があっても管理インターフェースが自動的に開放されることはありません。
- uuid で完全一致の特定を行います。accountId/accountName はあいまい検索のままで、作成結果を復元する際はフィールドを完全一致で照合し、ページを走査する必要があります。ページ番号は 1 から始まり、デフォルトは 1 ページ 10 件です。レスポンスのページングはトップレベルの pageInfo にあり、レコードは content.data に格納され、content.declaration はワークスペースの宣言を踏襲します。
- 各レコードは既存の一覧構造を保持し、トップレベルに platformAccountId と platformAuthorizationStatus を補足します。信頼ポリシーの設定には config.externalId を使用します。
- プラットフォームアカウント ID は、現在のワークスペースのブランドおよびレコードのパーティションに基づいて取得される現在の公開設定であり、履歴のアイデンティティスナップショットではありません。利用できない場合でもレコードと External ID は保持され、プラットフォーム ID は null、状態は unavailable になります。正常時は available で、他のブランドへのフォールバックは行いません。
- isAvailable は遅延する可能性があるヘルス状態です。今回の検証には変更インターフェースの dryRun=true を使用し、正式な保存には dryRun=false を使用してください。後続の一時認証情報取得では引き続きリアルタイム検証が実行されます。
- provider/authType/ワークスペースの上書きパラメータは受け取りません。作成レスポンスを失った場合は、まず照会して復元し、External ID を再生成しないでください。
リクエスト例¶
curl --get 'https://openapi.guance.com/api/v1/cloud_account/do/list' \
-H 'DF-API-KEY: <DF-API-KEY>' \
--data-urlencode pageIndex=1 \
--data-urlencode pageSize=10 \
--data-urlencode accountId=123456789012
レスポンス¶
HTTP 200、application/json。以下の例では、直接読み取れる主要フィールドを示します。
| フィールド | 型 | 説明 |
|---|---|---|
| content.data | array<object> | クラウドアカウント配列。空の場合は []。 |
| content.data[].id | integer | レコード番号。 |
| content.data[].uuid | string | clac_ クラウドアカウント UUID。後続の操作用。 |
| content.data[].workspaceUUID | string | 所属ワークスペース。 |
| content.data[].provider | string | この公開一覧では固定で aws。 |
| content.data[].config | object | 公開設定。長期認証情報の暗号文/平文は返しません。 |
| content.data[].config.authType | string | assume_role。 |
| content.data[].config.area | string | cn/intl パーティション。 |
| content.data[].config.accountId | string | 顧客の12桁の Account ID。 |
| content.data[].config.roleName | string | 顧客の IAM ロールのパス/名前。 |
| content.data[].config.accountName | string | 設定表示名。 |
| content.data[].config.externalId | string | 現在のレコードの External ID。信頼の復元に使用し、自動ローテーションは行いません。 |
| content.data[].config.extraTags | array<object> | 追加タグ。値がない場合は [] を補います。 |
| content.data[].config.extraTags[].key | string | タグキー。 |
| content.data[].config.extraTags[].value | string | タグ値。 |
| content.data[].isAvailable | integer または boolean | 遅延する可能性がある保存済みの可用性。現在のリアルタイム検証ではありません。 |
| content.data[].status | integer | 削除されていないレコードの状態。通常は 0。 |
| content.data[].creator | string | 作成アイデンティティ。 |
| content.data[].updator | string | 更新アイデンティティ。未更新の場合は空文字列。 |
| content.data[].createAt | integer | 作成 Unix 秒。 |
| content.data[].updateAt | integer | 更新 Unix 秒。未更新の場合は -1。 |
| content.data[].deleteAt | integer | 未削除の場合は -1。 |
| content.data[].creatorInfo | object または string | アイデンティティ摘要。不明な場合は空文字列。アカウント/Key/システムアイデンティティのフィールドは異なる場合があります。 |
| content.data[].updatorInfo | object または string | 作成アイデンティティ摘要と同様。実際のメールアドレスや連絡先として扱うことはできません。 |
| content.data[].integrationFileNames | array<string> | このアカウントに設定済みの収集インテグレーションファイル名。未設定の場合は []。収集の正常性は保証しません。 |
| content.data[].integrationFileNames[] | string | 単一のインテグレーションファイル識別子。 |
| content.data[].platformAccountId | string または null | 現在のブランド/パーティションに基づいて計算されたプラットフォーム ID。履歴スナップショットではありません。利用不可の場合は null。 |
| content.data[].platformAuthorizationStatus | string | available はプラットフォームの現在の設定が利用可能、unavailable は欠落/無効。顧客の Role 認可の成功を意味するものではありません。 |
| content.data[].creatorInfo.uuid | string | アイデンティティ UUID。システムアイデンティティの場合は空になることがあります。 |
| content.data[].creatorInfo.name | string | 表示名。 |
| content.data[].creatorInfo.email | string | アカウントのメールアドレス、Key UUID、またはシステム/AI ラベルの場合があり、一律にメールアドレスとして扱うことはできません。 |
| content.data[].creatorInfo.username | string | 条件付きで返されるログイン名。 |
| content.data[].creatorInfo.status | integer | 条件付きのアイデンティティ状態。 |
| content.data[].creatorInfo.wsAccountStatus | integer | 条件付きのワークスペース関係/互換状態。 |
| content.data[].creatorInfo.iconUrl | string | 条件付きのアバター。 |
| content.data[].creatorInfo.mobile | string | 条件付きの携帯電話番号。 |
| content.data[].creatorInfo.countryCode | string | 条件付きの国番号。 |
| content.data[].creatorInfo.acntWsNickname | string | 条件付きのワークスペースニックネーム。 |
| content.data[].updatorInfo.uuid | string | アイデンティティ UUID。システムアイデンティティの場合は空になることがあります。 |
| content.data[].updatorInfo.name | string | 表示名。 |
| content.data[].updatorInfo.email | string | アカウントのメールアドレス、Key UUID、またはシステム/AI ラベルの場合があり、一律にメールアドレスとして扱うことはできません。 |
| content.data[].updatorInfo.username | string | 条件付きで返されるログイン名。 |
| content.data[].updatorInfo.status | integer | 条件付きのアイデンティティ状態。 |
| content.data[].updatorInfo.wsAccountStatus | integer | 条件付きのワークスペース関係/互換状態。 |
| content.data[].updatorInfo.iconUrl | string | 条件付きのアバター。 |
| content.data[].updatorInfo.mobile | string | 条件付きの携帯電話番号。 |
| content.data[].updatorInfo.countryCode | string | 条件付きの国番号。 |
| content.data[].updatorInfo.acntWsNickname | string | 条件付きのワークスペースニックネーム。 |
| content.declaration | object | 外側のワークスペース宣言。 |
| pageInfo.pageIndex | integer | 現在のページ。1 から始まります。 |
| pageInfo.pageSize | integer | ページあたりの件数。 |
| pageInfo.count | integer | このページの件数。 |
| pageInfo.totalCount | integer | 一致するアカウントの総数。 |
| レスポンスヘッダー | 型 | 説明 |
|---|---|---|
| Cache-Control | string | no-store。成功時およびこのブループリントのルートエラー時はいずれもキャッシュを禁止します。 |
| Pragma | string | no-cache。 |
{
"code": 200,
"content": {
"data": [
{
"id": 100,
"uuid": "clac_example",
"workspaceUUID": "wksp_example",
"provider": "aws",
"config": {
"authType": "assume_role",
"area": "intl",
"accountId": "123456789012",
"roleName": "collection/ExampleCollector",
"accountName": "example-account",
"extraTags": [
{
"key": "env",
"value": "prod"
}
],
"externalId": "EXTERNAL-ID-EXAMPLE"
},
"isAvailable": false,
"status": 0,
"creator": "wsak_example",
"updator": "",
"createAt": 1785427200,
"updateAt": -1,
"deleteAt": -1,
"creatorInfo": {},
"updatorInfo": "",
"integrationFileNames": [],
"platformAccountId": "111111111111",
"platformAuthorizationStatus": "available"
}
],
"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 | リクエストフィールドの欠落、またはフィールド値が宣言された検証条件に違反 | パラメータ解析失敗 | パラメータの位置、フィールド名、型、値を確認します。 |
| 403 | ft.Forbidden | 管理用の4つのエントリーポイントが無料プランのワークスペースで明示的なバージョンチェックにより拒否 | 操作権限がありません | ワークスペースのプランと管理権限を確認し、該当する機能と認可を持つ対象ワークスペースに切り替えます。 |
| 400 | ft.ParamsValidateError | JSON Body が空オブジェクト {} でない、または以前に保存された AWS assume_role 設定がアカウント/ロール/External ID の仕様に適合しない | パラメータ検証失敗: {} | リクエストでは {} のみを送信します。過去の設定が不正な場合は、権限を持つクラウドアカウント管理フローで確認・修正し、このインターフェースでは dryRun/設定更新フィールドを送信しません。 |
| 500 | ft.CodeError | クラウドアカウント/過去の JSON/コレクター資料の読み取り、またはプラットフォーム認可表示で内部例外が発生 | 内部処理エラー | traceId と Query を保持し、過去の設定/データベースおよびプラットフォーム認可を確認します。この読み取りでは収集スクリプトのデプロイや設定書き込みは実行されません。 |