필드 매핑

필드 매핑을 사용하여 고객 매치 타겟팅 워크플로의 각 단계를 Google Ads API에서 Data Manager API로 업그레이드합니다.

• 잠재고객 관리 필드 매핑에는 잠재고객을 만들고, 업데이트하고, 검색하기 위한 필드 매핑이 포함되어 있습니다.

• 수집 필드 매핑에는 잠재고객 구성원을 추가하거나 삭제하기 위한 필드 매핑이 포함됩니다.

잠재고객 관리 필드 매핑

표의 매핑을 사용하여 Google Ads API의 UserList을 데이터 관리 도구 API의 UserList에 매핑합니다.

UserList (Google Ads API)	UserList (데이터 관리 도구 API)	참고
resource_name	name	자세한 내용은 리소스 이름을 참고하세요.
id	id
read_only	read_only
name	display_name	필수
description	description	필수
membership_status	membership_status
integration_code	integration_code
membership_life_span	membership_duration	잠재고객 구성원이 추가된 후 목록에 남아 있는 기간입니다. 값은 전체 일수에 상응해야 합니다. 설정하지 않으면 기본값은 최대값입니다. 타임스탬프 형식을 사용하여 값을 형식화합니다.
size_for_display	size_info.display_network_members_count
size_range_for_display	적용되지 않습니다.	크기 정보에는 size_info.display_network_members_count를 사용합니다.
size_for_search	size_info.search_network_members_count
size_range_for_search	적용되지 않습니다.	크기 정보에는 size_info.search_network_members_count를 사용합니다.
type	적용되지 않습니다.
access_reason	access_reason
account_user_list_status	account_access_status
closing_reason	closing_reason
eligible_for_search	target_network_info.eligible_for_search
eligible_for_display	target_network_info.eligible_for_display
match_rate_percentage	ingested_user_list_info.contact_id_info.match_rate_percentage
basic_user_list	ingested_user_list_info.pseudonymous_id_info	고객 매치 타겟팅에 사용되지 않습니다.
crm_based_user_list	ingested_user_list_info	필수사항. 고객 일치 타겟팅 잠재고객 정보를 참고하세요.
적용되지 않습니다.	ingested_user_list_info.pair_id_info	고객 매치 타겟팅에 사용되지 않습니다.
적용되지 않습니다.	ingested_user_list_info.partner_audience_info	고객 매치 타겟팅에 사용되지 않습니다.
logical_user_list	적용되지 않습니다.	고객 매치 타겟팅에 사용되지 않습니다.
logical_user_list	적용되지 않습니다.	고객 매치 타겟팅에 사용되지 않습니다.
lookalike_user_list	적용되지 않습니다.	고객 매치 타겟팅에 사용되지 않습니다.
rule_based_user_list	적용되지 않습니다.	고객 매치 타겟팅에 사용되지 않습니다.
similar_user_list	적용되지 않습니다.	고객 매치 타겟팅에 사용되지 않습니다.

고객 매치 타겟팅 잠재고객 정보

Google Ads API에서 고객 일치 타겟팅 잠재고객을 만들 때 crm_based_user_list 필드가 필요합니다.

Data Manager API에서 ingested_user_list_info 필드를 IngestedUserListInfo로 설정하여 해당 속성을 설정한 다음 고객 매치 및 사용자 데이터 유형에 필요한 필드를 설정합니다.

연락처 정보

upload_key_types

CONTACT_INFO이 포함된 목록으로 설정합니다.

contact_id_info

ContactIdInfo로 설정합니다.

data_source_type를 DATA_SOURCE_TYPE_FIRST_PARTY로 설정합니다.

모바일 ID

upload_key_types

MOBILE_ID이 포함된 목록으로 설정합니다.

mobile_id_info

MobileIdInfo로 설정합니다.

• data_source_type를 DATA_SOURCE_TYPE_FIRST_PARTY로 설정합니다.
• key_space를 IOS 또는 ANDROID으로 설정합니다.
• 데이터가 수집된 모바일 애플리케이션을 고유하게 식별하는 문자열로 app_id를 설정합니다. Google Ads API에서 앱 ID에 사용하는 것과 동일한 형식을 사용합니다.

사용자 ID

upload_key_types

USER_ID이 포함된 목록으로 설정합니다.

user_id_info

UserIdInfo로 설정합니다.

data_source_type를 DATA_SOURCE_TYPE_FIRST_PARTY로 설정합니다.

리소스 이름

데이터 관리 도구 API는 Google Ads API와 다른 리소스 이름 형식을 사용합니다.

Google Ads API

Google Ads API에서 UserList 리소스 이름은 다음 형식을 사용합니다.

customers/{customer_id}/userLists/{user_list_id}

Data Manager API

Data Manager API에서 UserList 리소스 이름은 다음 형식을 사용합니다.

accountTypes/{accountType}/accounts/{account}/userLists/{userList}

필드 매핑 업로드

표의 매핑을 사용하여 Google Ads API의 AddOfflineUserDataJobOperationsRequest을 데이터 관리 도구 API의 IngestAudienceMembersRequest에 매핑합니다.

요청 필드

AddOfflineUserDataJobOperationsRequest (Google Ads API)	IngestAudienceMembersRequest (Data Manager API)	참고
customer_id 필드 OfflineUserDataJob의 customer_match_user_list_metadata 필드 developer-token 요청 헤더 login-customer_id 요청 헤더 linked-customer-id 요청 헤더	destinations	고객 및 잠재고객 필드를 참고하세요.
consent에서 customer_match_user_list_metadata 의 OfflineUserDataJob	consent	요청에 있는 잠재고객 구성원의 선택적 기본 동의 설정입니다. AudienceMember의 consent 필드를 설정하여 개별 잠재고객 구성원의 이 값을 재정의할 수 있습니다.
- 동등한 보고서 없음	encoding	필수: UserIdentifier 값에 사용되는 Encoding로 설정합니다.
- 동등한 보고서 없음	encryption_info	요청에 암호화된 값이 포함되어 있는지 설정합니다. 자세한 내용은 암호화를 참고하세요.
job_id	- 동등한 보고서 없음	응답에서 반환된 request_id을 사용하여 진단을 가져옵니다.
enable_partial_failure	- 동등한 보고서 없음	데이터 관리 도구 API는 부분 실패를 지원하지 않습니다. IngestAudienceMembersRequest의 필드 중 하나라도 검증에 실패하면 Data Manager API는 전체 요청을 거부합니다. 진단을 사용하여 처리 오류를 가져옵니다.
enable_warnings	- 동등한 보고서 없음	Data Manager API는 응답에 경고를 보고하지 않습니다. 진단을 사용하여 처리 경고를 가져옵니다.
validate_only	validate_only
operations	audience_members	잠재고객 구성원 목록입니다. 자세한 내용은 잠재고객 구성원 필드 섹션을 참고하세요.
- 동등한 보고서 없음	terms_of_service	필수사항. 사용자가 고객 일치 타겟팅의 서비스 약관에 동의했는지 또는 거부했는지를 나타내도록 설정합니다.

고객 및 잠재고객 필드

Google Ads API는 작업당 하나의 잠재고객에만 잠재고객 구성원을 업로드하는 것을 지원합니다.또한 developer-token 요청 헤더가 필요하며, 다양한 인증 시나리오에 대해 login-customer-id 및 linked-customer-id 요청 헤더를 설정합니다.

데이터 관리 도구 API는 단일 요청에서 여러 잠재고객의 잠재고객 구성원을 전송하는 기능을 지원합니다. Data Manager API에는 개발자 토큰이 필요하지 않으며 요청 헤더 대신 Destination 필드를 사용하여 로그인 및 연결된 고객 정보를 지정합니다. 대상에 관한 자세한 내용은 대상 구성을 참고하세요.

데이터 관리 도구 API는 잠재고객의 모든 구성원을 삭제하는 것을 지원하지 않습니다. Google Ads API에서는 OfflineUserDataJobOperation의 remove_all 필드를 true로 설정하여 잠재고객의 모든 회원을 삭제할 수 있습니다.

단일 잠재고객의 Google Ads API 필드를 Destination의 상응하는 필드에 매핑하는 방법은 다음과 같습니다.

Google Ads API	Destination (Data Manager API)	참고
요청의 customer_id	operating_account	account_id를 잠재고객의 고객 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	account_id를 연결된 계정의 고객 ID로 설정합니다. account_type를 DATA_PARTNER로 설정합니다.
OfflineUserDataJob의 customer_match_user_list_metadata에서 user_list	product_destination_id	필수사항. 잠재고객의 숫자 ID로 설정됩니다. UserList의 리소스 이름을 사용하지 마세요.
- 동등한 보고서 없음	reference	Destination의 사용자 정의 식별자입니다. 단일 요청에서 여러 잠재고객의 잠재고객 구성원을 전송하는 경우 이 필드를 설정합니다.

잠재고객 회원 필드

UserData (Google Ads API)	AudienceMember (Data Manager API)	참고
consent	consent	잠재고객 구성원의 동의를 지정하도록 설정됩니다. 두 API 모두 유사한 Consent 객체(ad_user_data, ad_personalization)를 사용합니다. 데이터 관리 도구 API의 경우 요청 수준 consent 필드를 설정하여 요청에 있는 모든 잠재고객 구성원의 동의를 설정할 수도 있습니다.
transaction_attribute	적용되지 않습니다.	고객 매치 타겟팅에는 적용되지 않습니다.
user_attribute	적용되지 않습니다.	고객 매치 타겟팅에는 적용되지 않습니다.
user_identifiers	mobile_id_data user_id_data user_identifiers	잠재고객 구성원에게 전송하는 데이터 유형에 해당하는 필드를 채웁니다. 자세한 내용은 사용자 식별자 필드를 참고하세요.

사용자 식별자 필드

Google Ads API에서는 연락처 정보, 모바일 ID 또는 사용자 ID를 전송하는지 여부에 관계없이 UserIdentifier를 사용합니다. 데이터 관리 도구 API는 각 데이터 유형에 대해 서로 다른 필드를 사용하는 다른 접근 방식을 사용합니다.

Data Manager API에서 전송하는 데이터 유형에 해당하는 필드를 입력합니다.

연락처 정보

이메일 주소, 전화번호 또는 주소 정보와 같은 연락처 정보를 사용하는 경우 user_data를 각 연락처 정보 항목에 대해 user_identifiers에 별도의 항목이 있는 UserData로 설정합니다.

UserIdentifier (Google Ads API)	UserIdentifier (Data Manager API)	참고
address_info	address	자세한 내용은 주소 필드를 참고하세요.
hashed_email	email_address	형식이 지정되고 해싱된 이메일 주소로 설정됩니다. 해시된 이메일 주소를 암호화할 수도 있습니다.
hashed_phone_number	phone_number	형식이 지정되고 해싱된 전화번호로 설정됩니다. 해싱된 전화번호를 암호화할 수도 있습니다.
user_identifier_source	적용되지 않습니다.

주소 필드

다음은 Google Ads API의 OfflineUserAddressInfo와 데이터 관리 도구 API의 AddressInfo 간의 필드 매핑입니다. 연락처 정보를 사용하여 고객 일치 타겟팅 잠재고객을 채우는 경우 이러한 매핑을 사용하세요.

OfflineUserAddressInfo (Google Ads API)	AddressInfo (Data Manager API)	참고
city	적용되지 않습니다.
country_code	region_code
hashed_first_name	given_name	형식이 지정되고 해싱된 이름으로 설정됩니다. 해시된 성명을 암호화할 수도 있습니다.
hashed_last_name	family_name	형식이 지정되고 해싱된 계열 이름으로 설정됩니다. 해시된 가족 이름을 암호화할 수도 있습니다.
hashed_street_address	적용되지 않습니다.
postal_code	postal_code
state	적용되지 않습니다.

모바일 ID

모바일 ID를 사용하는 경우 각 ID의 mobile_ids 항목과 함께 mobile_data를 MobileData로 설정합니다.

UserIdentifier (Google Ads API)	MobileData (Data Manager API)	참고
mobile_id	mobile_ids	잠재고객 구성원의 모바일 ID 목록으로 설정됩니다. Google Ads API에서는 잠재고객 구성원의 모든 모바일 ID에 대해 mobile_id가 있는 별도의 UserIdentifier를 추가합니다. Data Manager API에서 mobile_ids이 잠재고객 구성원의 모든 모바일 ID 목록으로 설정된 단일 MobileData를 추가합니다.
user_identifier_source	적용되지 않습니다.

사용자 ID

사용자 ID를 사용하는 경우 user_id_data를 UserIdData로 설정하고 user_id를 잠재고객 구성원의 사용자 ID로 설정합니다.

UserIdentifier (Google Ads API)	UserIdData (Data Manager API)	참고
third_party_user_id	user_id	Google Ads API에서는 잠재고객 구성원의 모든 사용자 ID에 대해 third_party_user_id가 있는 별도의 UserIdentifier를 추가합니다. Data Manager API에서 user_id_data 필드를 UserIdData로 설정하고 user_id 필드를 잠재고객 구성원의 사용자 ID로 설정합니다. 동일한 잠재고객 구성원에 대해 여러 사용자 ID를 보낼 수 없습니다.
user_identifier_source	적용되지 않습니다.