创建 AWS Role 云账号¶

POST /api/v1/cloud_account/do/add

Body 请求参数¶

参数补充说明¶

端到端步骤参见 通过 OpenAPI 接入 AWS 云账号。示例中的 Endpoint 取自 OpenAPI 站点列表。

仅支持 AWS assume_role；调用方须有当前工作空间的 cloudAccount.accountManage 权限。免费版不可用。使用 DF-API-KEY，该权限不自动包含临时凭证读取权限。

第三方自动化授权¶

1. 创建配置并保存返回的 uuid、externalId、platformAccountId。首次验证可能失败，但配置仍可保存；HTTP 成功不表示 AWS 授权已通过。
2. 第三方使用客户已授权的 AWS IAM/CloudFormation 权限创建 Role、配置采集所需的读取权限，并设置以下信任策略。cn 对应 aws-cn，intl 对应 aws；将平台账号 ID 和 External ID 替换为本条记录返回值。OpenAPI 不代管客户 AWS 资源，也不接收客户 AK/SK。

   {"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"AWS":"arn:<partition>:iam::<platformAccountId>:root"},"Action":"sts:AssumeRole","Condition":{"StringEquals":{"sts:ExternalId":"<externalId>"}}}]}
   

3. Role 的路径/名称须与 config.roleName 一致。客户部署完成后调用修改接口 {"config":{},"dryRun":true} 验证；通过后再传 dryRun=false 重新验证并保存。对 IAM 传播延迟做有上限的退避，不重复创建或轮换 External ID。角色的权限策略和信任策略是两项独立配置；仅信任成功不保证所有采集服务权限齐全。
4. 多账号自动化逐客户 AWS 账号保存 UUID/External ID 映射，不共享 External ID。云账号管理不会自动安装采集器。

返回与恢复¶

• creationResult.status：created 或 failed；validationResult.status：not_run、passed 或 failed，各自携带 code/message。一次验证包含原有正确/缺失/错误 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。未找到也不能将一次查询视为此前请求必未提交，应有界查询、核对冲突结果后再决定重试。
• 参数/鉴权/冲突等验证前失败为 not_run；验证完成后锁或提交失败仍保留本次 passed/failed。5xx 返回安全通用错误及 traceId，不返回原始 SQL/AWS 响应。

AWS 参考：第三方跨账号授权、CloudFormation Role。

请求例子¶

curl -X POST '<Endpoint>/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/Guance", "accountName": "example", "extraTags": []}}'

响应¶

{
    "code": 200,
    "success": true,
    "errorCode": "",
    "message": "",
    "content": {
        "uuid": "clac_example",
        "externalId": "generated-external-id",
        "platformAccountId": "111111111111",
        "isAvailable": false,
        "creationResult": {
            "status": "created",
            "code": "",
            "message": ""
        },
        "validationResult": {
            "status": "failed",
            "code": "ft.CloudAccountAuthInvalid",
            "message": "云账号授权无效"
        },
        "declaration": {}
    },
    "traceId": "TRACE-example"
}