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입니다. 양의 정수를 사용하는 것이 좋습니다. 공개적으로 최댓값이 선언되어 있지 않고 서버에서도 별도의 통일된 상한을 제한하지 않으므로 한 번의 요청이 너무 커지지 않도록 하십시오. 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부터 시작하고 기본 페이지 크기는 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 Role 경로/이름. |
| 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 구성이 계정/Role/External ID 규격에 맞지 않음 | 파라미터 검증 실패: {} | 요청은 {}만 제출하십시오. 기존 구성이 유효하지 않은 경우 권한이 있는 클라우드 계정 관리 절차를 통해 확인하고 수정하며, 이 인터페이스에서 dryRun/구성 업데이트 필드를 전달하지 마십시오. |
| 500 | ft.CodeError | 클라우드 계정/기존 JSON/수집기 자료 또는 플랫폼 권한 부여 표시를 읽는 중 내부 예외 발생 | 내부 처리 오류 | traceId 및 Query를 보존하고 기존 구성/데이터베이스 및 플랫폼 권한 부여를 확인하십시오. 이 읽기는 수집 스크립트 배포 또는 구성 쓰기를 수행하지 않습니다. |