표의 매핑을 사용하여 Google Ads API 메서드와 필드를 Data Manager API의 IngestEventsRequest에 상응하는 항목에 매핑합니다.
API 메서드
Data Manager API를 사용하면 각 오프라인 매장 판매 이벤트 배치를 단일 IngestEventsRequest에 업로드할 수 있습니다.
반면 Google Ads API에서는 OfflineUserDataJobService를 사용하여 다음 세 단계를 거쳐야 했습니다.
CreateOfflineUserDataJob를 사용하여 작업 만들기AddOfflineUserDataJobOperations를 사용하여 작업에 작업 추가RunOfflineUserDataJob을 사용하여 작업을 실행합니다.
요청 필드
각 IngestEventsRequest에는 요청 한도가 적용됩니다. AddOfflineUserDataJobOperations 요청의 작업 수가 이러한 한도를 초과하는 경우 여러 Data Manager API 수집 요청으로 분할해야 합니다.
Google Ads API 요청의 필드가 데이터 관리 도구 API에 매핑되는 방식은 다음과 같습니다.
CreateOfflineUserDataJobRequest
다음 표는 CreateOfflineUserDataJobRequest의 필드가 IngestEventsRequest에 매핑되는 방식을 보여줍니다.
CreateOfflineUserDataJobRequest (Google Ads API) |
IngestEventsRequest (Data Manager API) |
참고 |
|---|---|---|
customer_id |
destinations.operating_account |
고객 및 전환 액션 필드를 참고하세요. |
|
destinations |
고객 및 전환 액션 필드를 참고하세요. |
|
진단 | IngestEventsResponse에서 반환된 request_id를 사용하여 전환 업로드에 관한 진단을 가져옵니다. |
job.id |
request_id |
IngestEventsResponse에서 반환된 request_id를 사용하여 전환 업로드에 관한 진단을 가져옵니다. |
job.external_id |
- 동등한 보고서 없음 | |
job.type |
- 동등한 보고서 없음 | |
job.store_sales_metadata.third_party_metadata.partner_id |
destinations.login_account |
오프라인 매장 판매 전환을 업로드하는 데이터 파트너는 대상의 login_account로 식별됩니다. 자세한 내용은 대상 구성을 참고하세요. |
job.store_sales_metadata.third_party_metadata.advertiser_upload_date_time |
- 동등한 보고서 없음 | |
job.store_sales_metadata.third_party_metadata.valid_transaction_fraction |
- 동등한 보고서 없음 | |
job.store_sales_metadata.third_party_metadata.partner_match_fraction |
- 동등한 보고서 없음 | |
job.store_sales_metadata.third_party_metadata.partner_upload_fraction |
- 동등한 보고서 없음 | |
job.store_sales_metadata.third_party_metadata.bridge_map_version_id |
- 동등한 보고서 없음 | |
job.store_sales_metadata.loyalty_fraction |
- 동등한 보고서 없음 | |
job.store_sales_metadata.transaction_upload_fraction |
- 동등한 보고서 없음 | |
job.store_sales_metadata.custom_key |
|
이벤트 수준의 CustomVariable 또는 상품 수준의 ItemCustomVariable의 variable 필드에 매핑합니다. |
enable_match_rate_range_preview |
- 동등한 보고서 없음 | |
validate_only |
validate_only |
|
| - 동등한 보고서 없음 | consent |
Google Ads API는 UserData의 이벤트 수준에서만 consent 지정을 지원합니다. 데이터 관리 도구 API의 경우 IngestEventsRequest에서 consent 필드를 설정하여 요청의 모든 이벤트에 대한 동의를 지정할 수 있습니다. Event의 consent 필드를 설정하여 개별 이벤트의 이 값을 재정의할 수 있습니다. |
| - 동등한 보고서 없음 | encoding |
UserData 업로드에 필요합니다. UserIdentifier 값에 사용된 Encoding로 설정됩니다. |
| - 동등한 보고서 없음 | encryption_info |
요청에 암호화된 UserData 사용자 식별자가 포함된 경우 설정됩니다. 자세한 내용은 암호화를 참고하세요. |
AddOfflineUserDataJobOperationsRequest
다음 표는 AddOfflineUserDataJobOperationsRequest의 필드가 IngestEventsRequest에 매핑되는 방식을 보여줍니다.
AddOfflineUserDataJobOperationsRequest (Google Ads API) |
IngestEventsRequest (Data Manager API) |
참고 |
|---|---|---|
|
destinations |
고객 및 전환 액션 필드를 참고하세요. |
resource_name |
- 동등한 보고서 없음 | Data Manager API는 작업 리소스를 업데이트할 필요가 없습니다. |
enable_partial_failure |
- 동등한 보고서 없음 | IngestEventsRequest가 성공하면 다운스트림 처리 중에 발생하는 오류는 이벤트 수준에서 처리되므로 일부 성공이 발생할 수 있습니다. 진단을 사용하여 업로드 상태는 물론 개별 이벤트의 오류 및 경고를 검색합니다. IngestEventsRequest이 실패하면 (예: BadRequest로 인해) 이벤트가 처리되지 않으므로 오류를 해결하고 요청을 다시 시도해야 합니다. 자세한 내용은 API 오류 이해하기를 참고하세요. |
enable_warnings |
- 동등한 보고서 없음 | 진단을 사용하여 Data Manager API 요청에 관한 경고를 가져옵니다. 사용 설정할 필요는 없습니다. |
operations |
events |
OfflineUserDataJobOperation.create 작업은 IngestEventsRequest을 전송하는 것과 동일합니다. Data Manager API는 이벤트 삭제를 지원하지 않습니다. |
validate_only |
validate_only |
|
| - 동등한 보고서 없음 | consent |
Google Ads API는 UserData의 이벤트 수준에서만 consent 지정을 지원합니다. 데이터 관리 도구 API의 경우 IngestEventsRequest에서 consent 필드를 설정하여 요청의 모든 이벤트에 대한 동의를 지정할 수 있습니다. Event의 consent 필드를 설정하여 개별 이벤트의 이 값을 재정의할 수 있습니다. |
| - 동등한 보고서 없음 | encoding |
UserData 업로드에 필요합니다. UserIdentifier 값에 사용된 Encoding로 설정됩니다. |
| - 동등한 보고서 없음 | encryption_info |
요청에 암호화된 UserData 사용자 식별자가 포함된 경우 설정됩니다. 자세한 내용은 암호화를 참고하세요. |
고객 및 전환 액션 필드
Google Ads API에는 developer-token 요청 헤더가 필요하며, 다양한 인증 시나리오에 대해 login-customer-id 및 linked-customer-id
요청 헤더를 설정합니다.
Data Manager API에는 개발자 토큰이 필요하지 않으며 요청 헤더 대신 Destination의 필드를 사용하여 로그인 및 연결된 고객 정보를 지정합니다. 대상에 대한 자세한 내용은 대상 구성을 참고하세요.
| Google Ads API | Destination (Data Manager API) |
참고 |
|---|---|---|
요청의 customer_id |
operating_account |
account_id를 Google Ads 전환 계정의 고객 ID로 설정합니다. operating_account의 account_type를 GOOGLE_ADS로 설정합니다. |
developer-token 요청 헤더 |
- 동등한 보고서 없음 | 데이터 관리 도구 API에는 개발자 토큰이 필요하지 않습니다. |
login-customer-id 요청 헤더 |
login_account |
account_id을 로그인 계정의 고객 ID로 설정합니다. 로그인 계정이 Google Ads 계정인 경우 account_type을 GOOGLE_ADS로 설정하고, 로그인 계정이 데이터 파트너 계정인 경우 DATA_PARTNER로 설정합니다. |
linked-customer-id 요청 헤더 |
linked_account |
파트너 링크를 사용하여 operating_account에 액세스하는 경우 account_id을 연결된 계정의 고객 ID로 설정하고 account_type을 DATA_PARTNER로 설정합니다. 그렇지 않으면 linked_account 필드를 설정하지 마세요. |
conversion_action |
product_destination_id |
전환 액션의 숫자 ID로 설정됩니다. 리소스 이름을 사용하지 마세요. |
이벤트 필드
다음 표는 두 API 간에 오프라인 매장 판매 전환의 필드가 매핑되는 방식을 보여줍니다.
ItemAttribute를 사용하여 트랜잭션당 하나의 항목만 포함할 수 있는 Google Ads API와 달리 Data Manager API는 CartData에서 이벤트당 여러 항목을 포함할 수 있습니다.
OfflineUserDataJobOperation.create (Google Ads API) |
Event (Data Manager API) |
참고 |
|---|---|---|
| - 동등한 보고서 없음 | event_source |
필수사항 오프라인 매장 판매 전환의 경우 IN_STORE로 설정됩니다. |
transaction_attribute.conversion_action |
destinations.product_destination_id |
고객 및 전환 액션 필드를 참고하세요. 리소스 이름 대신 전환 액션의 숫자 ID를 사용합니다. |
transaction_attribute.transaction_date_time |
event_timestamp |
자세한 내용은 타임스탬프 형식을 참고하세요. |
transaction_attribute.transaction_amount_micros |
|
마이크로 단위의 값이 아닌 통화 값으로 설정합니다. 예를 들어 전환 가치가 5.23달러인 경우 5.23 값을 사용합니다. |
transaction_attribute.currency_code |
currency |
필수사항. |
transaction_attribute.order_id |
transaction_id |
필수사항. |
transaction_attribute.store_attribute.store_code |
event_location.store_id |
필수사항 EventLocation 객체의 store_id 필드에 판매점 코드를 설정합니다. |
transaction_attribute.custom_value |
|
이벤트 수준의 CustomVariable 또는 상품 수준의 ItemCustomVariable의 value 필드에 매핑합니다. |
transaction_attribute.item_attribute.item_id |
cart_data.items[].merchant_product_id |
|
transaction_attribute.item_attribute.merchant_id |
|
cart_data.merchant_id를 설정하면 모든 상품의 기본값으로 작동하지만 개별 상품에 대해 재정의할 수 있습니다. |
transaction_attribute.item_attribute.country_code |
|
cart_data.merchant_feed_label를 설정하면 모든 상품의 기본값으로 작동하지만 개별 상품에 대해 재정의할 수 있습니다. |
transaction_attribute.item_attribute.language_code |
|
cart_data.merchant_feed_language_code를 설정하면 모든 상품의 기본값으로 작동하지만 개별 상품에 대해 재정의할 수 있습니다. |
transaction_attribute.item_attribute.quantity |
cart_data.items[].quantity |
|
| - 동등한 보고서 없음 | cart_data.items[].unit_price |
이 상품의 세금, 배송비, 이벤트 범위 (거래 수준) 할인을 제외한 단가로 설정됩니다. |
user_identifiers |
|
필수사항:
|
consent |
consent |
두 API 모두 유사한 Consent 객체 (ad_user_data, ad_personalization)를 사용합니다. Data Manager API의 경우 IngestEventsRequest에서 consent 필드를 설정하여 요청의 모든 이벤트에 대한 동의를 설정할 수도 있습니다. |
사용자 식별자 필드
UserIdentifier (Google Ads API) |
UserIdentifier (Data Manager API) |
참고 |
|---|---|---|
user_identifier_source |
소스는 Data Manager API
|
|
hashed_email |
email_address |
형식이 지정되고 해싱된 이메일 주소로 설정됩니다. 해시된 이메일 주소를 암호화할 수도 있습니다. |
hashed_phone_number |
phone_number |
형식이 지정되고 해싱된 전화번호로 설정됩니다. 해싱된 전화번호를 암호화할 수도 있습니다. |
address_info |
address |
AddressInfo 객체로 설정됩니다. 형식 지정 및 해싱 가이드라인을 따릅니다. 주소의 해시된 속성을 암호화할 수도 있습니다. |
address_info.hashed_first_name |
address.given_name |
|
address_info.hashed_last_name |
address.family_name |
|
address_info.country_code |
address.region_code |
|
address_info.postal_code |
address.postal_code |
|
address_info.city |
- 동등한 보고서 없음 | 현재 버전의 Data Manager API에서는 지원되지 않습니다. |
address_info.state |
- 동등한 보고서 없음 | 현재 버전의 Data Manager API에서는 지원되지 않습니다. |
address_info.hashed_street_address |
- 동등한 보고서 없음 | 현재 버전의 Data Manager API에서는 지원되지 않습니다. |