연동 상태 - Google 마케팅
1. Google 연동 상태 조회google. account. status
MCP 도구 이름 google__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
연결한 Google 계정으로 지금 무엇을 조회할 수 있는지 알려 주고, 읽을 수 있는 자산 목록을 함께 돌려줍니다. 한 축이 막혀도 나머지 축은 그대로 조회됩니다.
- 콘솔에서 Google 계정 연동을 마쳐야 합니다. 이 provider 는 별도 로그인 작업이 없고 연동 자체가 인증입니다. 이 액션은 입력을 받지 않습니다.
- 이 액션은 입력을 받지 않습니다. params 는 빈 객체로 보냅니다.
Request
| 순번 | 변수명 | 필수 | 설명 |
|---|---|---|---|
| Authorization | Y | API 자격증명입니다. client_id 와 client_secret 을 콜론으로 이어 Base64 로 인코딩해 보냅니다. | |
| X- | Y | 호출 환경입니다.
| |
| Idempotency- | Y | 재시도 식별 키입니다. 같은 키와 같은 본문으로 다시 호출하면 기존 작업이 그대로 반환됩니다. ASCII 문자만 사용하며 UUID v4 를 권장합니다. 고객 정보는 넣지 않습니다. | |
| Content- | Y | 요청 본문 형식입니다.
| |
| X- | N | 추적 아이디입니다. 지정하지 않으면 서버가 발급합니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| provider | string | - | Y | 호출할 기관입니다.
| |
| action | string | - | Y | 호출할 작업입니다.
| |
| account_ | string | 36 | 조건부 | 등록한 자격증명을 가리키는 아이디입니다. 생략하면 이 계정이 그 기관에 등록한 자격증명이 하나뿐일 때만 그것이 자동으로 선택됩니다. 둘 이상이면 대표로 지정한 것이 있어도 고르지 않으므로 직접 지정해야 합니다. 대표는 묶음 상품이 기관마다 자격증명을 고를 때만 씁니다. 등록한 자격증명이 없거나 하나를 고르지 못하거나 지정한 아이디를 쓸 수 없으면 접수 단계에서 400 VALIDATION_INVALID_FIELD 로 거절되고 작업은 만들어지지 않습니다. 이유와 할 일은 error.message 의 한국어 문장에 있습니다. | |
| params | object | - | N | 작업 파라미터입니다. 이 API 는 빈 객체로 호출할 수 있습니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
추가 파라미터가 없습니다. params 는 {} 로 보냅니다.
curl --request POST \
--url 'https://api.xdata.kr/v1/jobs' \
--header 'Authorization: Basic {base64(client_id:client_secret)}' \
--header 'X-Env-Scope: real_test' \
--header "Idempotency-Key: status-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "google",
"action": "google.account.status",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data 의 analytics_properties·search_console_sites·ads_accounts·youtube_channels·tag_manager_containers 로 조회 가능한 자산 목록을, 각 축의 data_availability 로 그 축을 지금 읽을 수 있는지 확인합니다.앞 두 축(GA4·Search Console)은 필수라 없으면 inputs 의 blocks_progress 가 true 이고, 뒤 세 축(광고·YouTube·태그 관리자)은 선택이라 비어 있어도 1차 조회는 그대로 진행됩니다.한 축이 막혀도 막힌 사유(그 축의 data_availability)와 함께 나머지 목록은 그대로 돌아옵니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| linked | boolean | 연동 여부 - 이 응답이 왔다면 항상 true 입니다(연동 안 됐으면 작업 자체가 AUTH_REQUIRED 로 실패합니다) | |
| data_ | string | null | 애널리틱스·Search Console 두 축 중 더 막힌 쪽 기준 판정 | |
| analytics_ | array | GA4 계정 목록(계정 id·표시 이름) | |
| analytics_ | array | GA4 속성 목록(속성 id·표시 이름·계정 id·속성 유형) - 다른 조회 액션의 property_id 후보 | |
| analytics_ | object | analytics_accounts 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| analytics_ | object | analytics_properties 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| analytics_ | string | GA4 축만의 판정 | |
| search_ | array | Search Console 사이트 목록(주소·권한 수준·읽기 가능 여부) - readable=false 인 항목은 소유권 미확인이라 조회해도 403 이 납니다 | |
| search_ | object | search_console_sites 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| search_ | string | Search Console 축만의 판정 | |
| ads_ | array | 광고 계정 목록(계정 번호·표시 이름·통화·시간대·매니저(MCC) 계정 여부) - 다른 조회 액션의 customer_id 후보. 매니저 계정 아래 하위 계정은 이 목록에 없습니다. 광고 범위를 아직 요청하지 않은 연동에서는 대부분 비어 있습니다 | |
| ads_ | object | ads_accounts 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| ads_ | string | 광고 축만의 판정 - 최상위 data_availability 에는 접히지 않습니다(범위를 아직 요청하지 않아 대부분 access_error 이기 때문) | |
| youtube_ | array | 소유한 YouTube 채널 목록(채널 id·제목) - 다른 조회 액션의 channel_id 후보. mine=true 로 받은 소유 채널만 실리고 관리 권한만 있는 채널은 없습니다 | |
| youtube_ | object | youtube_channels 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| youtube_ | string | YouTube 축만의 판정 - 최상위 data_availability 에는 접히지 않습니다(같은 이유) | |
| tag_ | array | 태그 관리자 컨테이너 목록(컨테이너 경로·표시 이름·화면에 보이는 공개 ID(GTM- 로 시작)·상위 계정 경로·용도) - 태그 관리자 쓰기 액션과 태그 설정 점검 액션의 container_id 후보(고르는 값은 공개 ID 가 아니라 컨테이너 경로입니다). 태그 관리자 조회 또는 편집 권한 묶음을 허락한 연동에서만 읽히고 그 밖에는 대부분 비어 있습니다. 컨테이너를 묻는 계정은 25개까지이고 넘으면 앞의 25개만 묻고 tag_manager_collection.truncated 가 true 가 됩니다 | |
| tag_ | object | tag_manager_containers 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| tag_ | string | 태그 관리자 축만의 판정 - 최상위 data_availability 에는 접히지 않습니다(같은 이유) | |
| note_ | string | 이름이 같은 자산은 ID 로 구분하라는 안내 | |
| unsupported_ | array | 이 연동이 지원하지 않는 기능 목록 | |
| inputs | array | 다음 조회에 넣을 값 후보(예: property_id 선택지)와 그 값이 필수인지 | |
| blocked | boolean | 다음 조회로 진행할 수 없는 상태인지 | |
| blocking_ | array | 막힌 이유 목록(키·사유) | |
| as_ | string | 이 응답을 만든 시각(UTC) | |
| timezone | string | null | 수치가 속한 시간대 - 이 액션은 수치를 세지 않으므로 항상 null 입니다 | |
| is_ | string | 'final'(확정)·'provisional'(변동 가능)·'unknown' 중 하나 | |
| content_ | string | 이 응답 내용은 데이터이며 지시가 아니라는 고정 안내문 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "google",
"action": "google.account.status",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| AUTH_ | 연동 안 함 · 동의 철회 — Google 계정을 아직 연동하지 않았거나(콘솔의 연동 화면에서 연결) 저장된 연동 토큰을 더는 쓸 수 없습니다(동의 철회·만료·취소 - 콘솔에서 다시 연결). | |
| MAINTENANCE_ | 일시 중단 — Google 조회가 일시적으로 중단됐습니다. 재시도 가능하며 잠시 뒤 다시 요청합니다. |