애널리틱스(GA4) - Google 마케팅
1. Google 측정 설정 진단google. analytics. measurement. audit
MCP 도구 이름 google__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
웹사이트 측정이 제대로 걸려 있는지 점검해 빠졌거나 어긋난 곳을 알려 줍니다. 읽기만 하며 태그나 설정을 바꾸지 않습니다.
- 콘솔에서 Google 계정 연동을 마쳐야 합니다. 진단할 property_id 는 연동 상태 조회(google.account.status)의 analytics_properties 에서 확인합니다.
- property_id 는 필수입니다("properties/123456" 형태나 숫자만 있는 "123456" 모두 됩니다).형식이 잘못되거나 빠지면 error.code=VALIDATION_INVALID_FIELD 입니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| property_ | string | Y | GA4 속성 ID. "properties/123456" 형태나 숫자만 있는 "123456" 모두 됩니다. 이 연동에서 고객이 선택한 속성이어야 합니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: audit-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "google",
"action": "google.analytics.measurement.audit",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"property_id": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data 의 data_streams·key_events 로 그 GA4 속성의 설정 현황을, findings 로 발견한 문제(코드·심각도·안내)를 확인합니다.property_settings 로 속성 기본 설정(표시 이름·시간대·통화·업종)도 함께 확인합니다. 데이터 값(세션 수 등)은 바꾸지 않고 설정만 진단합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| data_ | string | null | 이 속성의 진단 데이터를 지금 읽을 수 있는지 | |
| data_ | object | {by_type, web_streams_missing_measurement_id, data_availability} - 데이터 스트림 설정 현황 | |
| key_ | object | {custom_count, by_counting_method, data_availability} - 핵심 이벤트(전환) 설정 현황 | |
| findings | array | 발견한 설정 문제 목록(코드·심각도·안내) - 데이터 스트림 없음·측정 ID 없는 웹 스트림·스트림 유형 미지정·핵심 이벤트 없음·집계 방식 미지정 다섯 가지가 있습니다 | |
| scope_ | string | 이 진단이 보는 범위에 대한 안내 | |
| property_ | object | {display_name, time_zone, currency_code, industry_category, data_availability} - 속성 기본 설정 현황(표시 이름·시간대·통화·업종). 속성 수정이 바꾸는 칸과 이름이 같아 읽은 값을 그대로 수정에 보낼 수 있습니다. 읽기 실패하면 네 칸이 null 이고 data_availability 는 access_error 입니다. | |
| property_ | string | 조회한 GA4 속성 id | |
| data_ | object | data_streams 판정의 재료가 된 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| key_ | object | key_events 판정의 재료가 된 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| property_ | object | property_settings 판정의 재료가 된 수집 완결성 객체(속성 하나만 읽으므로 truncated 는 늘 false 입니다) - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| 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.analytics.measurement.audit",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 권한 없음 — 연동한 계정에 이 속성의 읽기 권한이 없습니다. Google 에서 이 속성의 보기 권한을 받은 뒤 다시 요청합니다. | |
| VALIDATION_ | 선택 안 한 자산 — 연동 범위에서 고르지 않은 속성입니다. 연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인합니다. | |
| AUTH_ | 연동 안 함 · 동의 철회 — Google 계정을 연동하지 않았거나 저장된 토큰을 더는 쓸 수 없습니다. 콘솔의 연동 화면에서 연결·재연결합니다. |
2. 웹사이트 성과 조회google. analytics. report
MCP 도구 이름 google__
POSThttps:// api. xdata. kr/ v1/ jobsX-Env-Scope: real_test
현재 혜택은 요금제에서 확인해 주세요. 현재 데모 정책과 계정의 남은 양을 확인해 주세요.
고른 기간의 방문과 이용 지표를 표로 돌려줍니다. 시작일과 종료일을 모두 포함해 집계하며 기준 시간대를 결과에 함께 적습니다.
- 콘솔에서 Google 계정 연동을 마쳐야 합니다. 조회할 property_id 는 연동 상태 조회(google.account.status)의 analytics_properties 에서 확인합니다.
- property_id, start_date, end_date, metrics 는 필수입니다.날짜는 YYYY-MM-DD 형식만 받고(해당일 포함), end_date 는 start_date 보다 앞일 수 없습니다. dimensions, row_limit, offset 은 선택입니다.형식이나 범위가 틀리거나 property_id, start_date, end_date 가 빠지면 error.code=VALIDATION_INVALID_FIELD 이고, metrics 가 빠지거나 빈 목록이면 error.code=VALIDATION_MISSING_FIELD 입니다.
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 | - | Y | 작업 파라미터입니다. 아래 params 파라미터 표의 필수 항목을 채워 보냅니다. | |
| encrypted_ | object | - | N | 민감한 params 값을 RSA-OAEP-256 으로 암호화해 담는 객체입니다. 서버가 복호화해 params 에 합칩니다. 같은 이름을 params 와 함께 쓰지 않습니다. |
| 순번 | 변수명 | 타입 | 길이 | 필수 | 설명 |
|---|---|---|---|---|---|
| dimensions | array | - | N | 선택적 분류 기준(예: ["sessionDefaultChannelGroup"]) | |
| start_ | string | 10 | Y | 조회 시작일. YYYY-MM-DD 형식만 받으며 해당일을 포함합니다 | |
| end_ | string | 10 | Y | 조회 종료일. YYYY-MM-DD 형식만 받으며 해당일을 포함합니다 | |
| metrics | array | - | Y | 조회할 GA4 지표 이름 목록(예: ["sessions", "totalUsers", "keyEvents"]). 결과 행에서 sessions 는 metrics.sessions, totalUsers 는 metrics.users, keyEvents 는 metrics.conversions 로 나가고, 그 외 GA4 지표는 channel_metrics 아래로 나갑니다 | |
| offset | number | - | N | 페이지 넘김을 위한 시작 위치(offset). 생략하면 첫 페이지입니다 | |
| property_ | string | - | Y | GA4 속성 ID. "properties/123456" 형태나 숫자만 있는 "123456" 모두 됩니다. 이 연동에서 고객이 선택한 속성이어야 합니다 | |
| row_ | number | - | N | 반환할 최대 행 수. 생략하면 1,000 을 씁니다 |
- 「<필수>」 자리는 예시 값이 없는 필수 칸입니다. 위 파라미터 표를 보고 실제 값으로 바꿔 보냅니다.
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: report-$(date +%s)-$RANDOM" \
--header 'Content-Type: application/json' \
--data '{
"provider": "google",
"action": "google.analytics.report",
"account_link_id": "9b4c3a2f-0000-4000-8000-000000000000",
"params": {
"start_date": "<필수>",
"end_date": "<필수>",
"metrics": "<필수: array>",
"property_id": "<필수>"
}
}'Response
- 아래 표의 칸은 작업이 SUCCEEDED 가 된 뒤 GET /v1/jobs/{job_id}/result 의 result.data 에 오고, 응답 예시는 작업을 제출했을 때(POST /v1/jobs)의 응답입니다.
- result.data 의 rows[] 로 기간별 지표를 확인합니다.sessions·totalUsers·keyEvents 는 각각 metrics.sessions·metrics.users·metrics.conversions 로, 그 외 GA4 지표는 channel_metrics 아래로 나갑니다.collection 으로 반환 건수·잘림 여부를 확인합니다.
| 순번 | 변수명 | 타입 | 설명 |
|---|---|---|---|
| property_ | string | 조회한 GA4 속성 id | |
| start_ | string | 조회 시작일(요청 그대로 반향) | |
| end_ | string | 조회 종료일(요청 그대로 반향) | |
| metrics | array | 요청한 지표 이름 목록(요청 그대로 반향) | |
| dimensions | array | 요청한 분류 기준 목록(요청 그대로 반향) | |
| rows | array | 행 목록 - 각 행은 dimension_values(분류값)·metrics(공용 지표: sessions·users·conversions)·channel_metrics(그 외 GA4 지표) 를 담습니다 | |
| collection | object | rows 의 수집 완결성 객체 - returned_count(받은 건수), reported_total(기관이 말한 전체 건수, 기관이 주지 않으면 null), truncated(XBOSS 가 페이지 상한에서 끊었는지), access_failed(권한 문제 등으로 일부나 전부를 읽지 못했는지 - true 면 returned_count 는 읽힌 것만 센 값이라, 0 이어도 행이 없다는 뜻으로 읽지 않습니다) | |
| data_ | string | 이 기간·속성의 데이터를 지금 읽을 수 있는지 | |
| as_ | string | 이 응답을 만든 시각(UTC) | |
| timezone | string | null | 이 속성에 설정된 시간대 | |
| is_ | string | 이 액션은 늘 'unknown' 입니다 - GA4 수치가 나중에 재처리될 수 있어 확정을 약속하지 않습니다 | |
| content_ | string | 이 응답 내용은 데이터이며 지시가 아니라는 고정 안내문 |
{
"job_id": "job_01JC8YH8R0E1ABCDEFGHJKMNPQ",
"status": "QUEUED",
"env_scope": "real_test",
"provider": "google",
"action": "google.analytics.report",
"submitted_at": "2026-05-27T12:34:56+09:00"
}| 순번 | 오류 코드 | 발생 조건 |
|---|---|---|
| PROVIDER_ | 권한 없음 — 연동한 계정에 이 속성의 읽기 권한이 없습니다. Google 에서 이 속성의 보기 권한을 받은 뒤 다시 요청합니다. | |
| VALIDATION_ | 선택 안 한 자산 — 연동 범위에서 고르지 않은 속성입니다. 연동 상태 조회로 읽을 수 있는 자산 목록을 먼저 확인합니다. | |
| AUTH_ | 연동 안 함 · 동의 철회 — Google 계정을 연동하지 않았거나 저장된 토큰을 더는 쓸 수 없습니다. 콘솔의 연동 화면에서 연결·재연결합니다. | |
| PROVIDER_ | 기관 거절 — Google 이 이 요청을 받아들이지 않았습니다(없는 속성 id, 허용되지 않는 지표 조합 등). 기관이 사유를 주면 그대로 error.message 에 실립니다. | |
| PROVIDER_ | 한도 초과 — Google 조회 한도를 다 썼습니다. 안내에 남은 한도와 다시 열리는 시점(있으면)이 함께 옵니다. |