通过 OpenAPI 接入 AWS 云账号¶

通过 OpenAPI，您可以为 AWS 账号创建角色授权配置、配置 IAM 信任关系、验证并保存授权。多账号场景中，可以为每个 AWS 账号重复执行同一流程。

准备工作¶

• 从 OpenAPI 站点列表 选择工作空间所在站点的 Endpoint。
• 准备该工作空间的 API Key。创建、查询、修改和删除需要云账号管理权限 cloudAccount.accountManage。这四个接口在免费版工作空间不可用。
• 准备客户 AWS 账号的 12 位账号 ID、分区和目标 IAM Role 名称。示例使用国际区（area=intl，分区 aws）及 collection/CloudCollection。中国区使用 area=cn，分区为 aws-cn。
• 确认执行程序已获客户授权，可在目标 AWS 账号创建 Role 和添加采集所需的权限。AWS CLI 示例假定当前 AWS 身份已配置为该账号内的授权身份。

以下示例使用环境变量 API_BASE 和 DF_API_KEY，分别表示 Endpoint（不带末尾斜杠）和从安全存储加载的工作空间 API Key。

1. 创建云账号配置¶

调用 创建 AWS Role 云账号。config.accountId 填写客户自己的 AWS 账号 ID。角色路径和名称须与下一步实际创建的 Role 一致。

curl -sS -X POST "$API_BASE/api/v1/cloud_account/do/add" \
  -H "DF-API-KEY: $DF_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"provider":"aws","config":{"authType":"assume_role","area":"intl","accountId":"123456789012","roleName":"collection/CloudCollection","accountName":"AWS collection"}}'

当 content.creationResult.status 为 created 时，保存以下字段的实际返回值：

创建配置和验证授权分别返回结果。首次调用时 Role 可能尚未创建，此时可以同时得到 creationResult.status=created 和 validationResult.status=failed。沿用已保存的 UUID 和 External ID，继续配置 AWS。

2. 创建 IAM Role 并配置信任策略¶

在客户 AWS 账号创建 Role。将以下 JSON 保存为 trust-policy.json，替换分区、平台 AWS 账号 ID 和 External ID。信任策略里的账号 ID 使用上一步返回的 platformAccountId。

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

可使用 AWS 控制台、AWS CLI 或部署模板完成配置。使用 AWS CLI 时，collection/CloudCollection 对应 Role 名称 CloudCollection 和 IAM 路径 /collection/。

aws iam create-role \
  --role-name CloudCollection \
  --path /collection/ \
  --assume-role-policy-document file://trust-policy.json

aws iam put-role-policy \
  --role-name CloudCollection \
  --policy-name CloudCollectionRead \
  --policy-document file://collection-policy.json

collection-policy.json 是经过客户审批的采集权限策略。参见 AWS 云集成角色授权配置 中的采集权限 JSON，并按实际采集的服务配置。信任策略控制谁可以承担 Role，权限策略控制承担 Role 后可以访问的 AWS 资源。

批量接入时，为每个 AWS 账号维护它自己的 UUID、分区、角色路径和 External ID。复用部署模板时，为每条记录注入对应值。已经存在同名 Role 时，先核对账号、路径和该 Role 的用途，再按客户的 IAM 变更流程更新信任和采集权限。

3. 验证并保存授权¶

将 CLOUD_ACCOUNT_UUID 设为创建返回的 UUID，调用 修改或验证 AWS Role 云账号。

curl -sS -X POST "$API_BASE/api/v1/cloud_account/$CLOUD_ACCOUNT_UUID/do/modify" \
  -H "DF-API-KEY: $DF_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"config":{},"dryRun":true}'

dryRun=true 只执行验证，content.saved=false 是预期结果。读取 content.validationResult.status。当结果为 passed 时，用同一 URL 提交 {"config":{},"dryRun":false}。正式保存会重新验证，只有本次响应同时满足 content.saved=true 和 content.validationResult.status=passed，才表示授权配置已成功验证并保存。

验证失败时，核对分区、角色路径、平台账号和 External ID。信任策略必须拒绝未带 External ID 或带错误 External ID 的承担请求。若 IAM 配置刚更新，可以用同一 UUID 做有限次数的退避重试。STS 验证通过后，按需配置 云集成采集器，并验证实际采集权限。

4. 查询、恢复或修改配置¶

用 查询 AWS Role 云账号 按 uuid 精确查找，或按 accountId 分页筛选。列表条目在 content.data，分页信息在响应顶层 pageInfo。

curl -sS --get "$API_BASE/api/v1/cloud_account/do/list" \
  -H "DF-API-KEY: $DF_API_KEY" \
  --data-urlencode "uuid=$CLOUD_ACCOUNT_UUID"

创建响应丢失时，先查已有记录。仅知道 AWS 账号 ID 时，accountId 是模糊过滤条件，须逐页精确比对 content.data[].config.accountId。如果重复创建返回 ft.CloudAccountAKRepeat，可使用 content.existingCloudAccountUUIDs 定位记录。恢复后继续使用 config.externalId 和该条记录的 platformAccountId。若平台授权状态为 unavailable，等待对应品牌和分区的平台配置恢复，再查询平台账号 ID。

如果创建遇到旧凭据冲突 ft.CloudAccountLegacyCredentialsConflict，先核对返回的旧记录 UUID，并评估其关联采集器，再处理原配置。修改接口支持别名、Role 名称和标签。账号 ID、分区、认证类型和 External ID 由已有记录确定。更新标签时省略 extraTags 会保留原值，传 [] 会清空。已有采集器在正式保存时可能重新同步。

5. 删除配置或读取临时凭证¶

停用接入时，核对目标 UUID 和关联采集器，再向 删除 AWS Role 云账号 发送 {}。删除会清理平台配置和关联采集器、任务。客户 AWS 侧 Role 由客户管理，历史观测数据保留。使用私有 Func 时，还应确认卸载任务执行完成。若之后重新创建，会得到新的 UUID 和 External ID，须按新值配置 IAM 信任策略。

如果应用需要临时凭证，使用具有 cloudAccount.temporaryCredentialsRead 权限的 API Key 调用 获取 AWS 临时凭证。接口每次实时验证已保存的授权，返回有期限的凭证。请按凭证有效期使用并避免将凭证写入日志。