이 가이드에는 클라이언트 라이브러리를 사용하지 않고 REST 엔드포인트를 직접 호출하는 예가 포함되어 있습니다.
기본 요건
여기에 표시된 모든 샘플은 curl 명령어를 사용하여 bash 셸에 복사하여 붙여넣기 위한 것입니다.
개발자 토큰(테스트 계정 액세스도 가능)과 하나 이상의 고객 계정이 포함된 Google Ads 관리자 계정도 필요합니다.
환경 변수
표시된 대로 계정 사용자 인증 정보와 ID를 입력한 다음 터미널에 복사하여 붙여넣어 후속 예에서 사용되는 환경 변수를 구성합니다. 승인 가이드에서는 OAuth 2.0 액세스 토큰을 생성하는 방법을 설명합니다.
API_VERSION="20"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"추가 선택적 객체 ID
다음 예 중 일부는 기존 예산 또는 캠페인에서 작동합니다. 이 예시에서 사용할 기존 객체의 ID가 있는 경우 표시된 대로 입력합니다.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID그렇지 않으면 두 Mutates - Creates examples가 새 예산과 캠페인을 만듭니다.
검색
쿼리 쿡북 가이드에는 일부 기본 Google Ads 화면에 해당하고 이 가이드에 사용된 것과 동일한 환경 변수를 사용하는 많은 보고 샘플이 포함되어 있습니다. 대화형 쿼리 빌더 도구는 맞춤 쿼리를 대화형으로 빌드하는 데도 유용합니다.
페이지 나눔
search 메서드는 페이지 크기가 10,000개 항목으로 고정되고 query와 함께 지정된 page_token을 사용하여 페이지로 나눕니다.
curl
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' ", "page_token":"${PAGE_TOKEN}" }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
curl
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data '{ "query": " SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED' " }'
GAQL
SELECT campaign.name, campaign_budget.amount_micros, campaign.status, campaign.optimization_score, campaign.advertising_channel_type, metrics.clicks, metrics.impressions, metrics.ctr, metrics.average_cpc, metrics.cost_micros, campaign.bidding_strategy_type FROM campaign WHERE segments.date DURING LAST_7_DAYS AND campaign.status != 'REMOVED'
변형
operations 배열을 채워 단일 JSON 요청 본문에서 여러 변이 작업 (create, update 또는 remove)을 전송할 수 있습니다.
생성
이 예시에서는 단일 요청으로 공유 캠페인 예산을 두 개 만듭니다.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } }, { 'create': { 'name': 'My Campaign Budget #${RANDOM}', 'amountMicros': 500000, } } ] }"
다음 예에서는 기존 캠페인 예산의 BUDGET_ID를 사용합니다. 이전 단계의 출력에서 복사하여 붙여넣을 수 있습니다.
BUDGET_ID=BUDGET_ID다른 리소스를 참조하는 리소스는 리소스 이름을 사용합니다. 다음 예에서 생성된 캠페인은 문자열 값 리소스 이름으로 campaignBudget를 참조합니다.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}', 'targetSpend': {} } } ] }"
업데이트
update 작업을 사용하여 기존 객체의 속성을 업데이트합니다. 다음 예에서는 기존 캠페인을 사용합니다. 이전 단계의 출력을 복사하여 붙여넣을 수 있습니다.
CAMPAIGN_ID=CAMPAIGN_ID모든 업데이트에는 업데이트로 적용되어야 하는 요청에 포함되어야 하는 JSON 속성의 쉼표로 구분된 목록인 updateMask 필드가 필요합니다. updateMask에 나열되어 있지만 요청 본문에 없는 속성은 객체에서 삭제됩니다. updateMask에 나열되지 않지만 요청 본문에 있는 속성은 무시됩니다.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'name': 'A changed campaign name #${RANDOM}', }, 'updateMask': 'name' } ], }"
삭제
객체는 리소스 이름을 remove 작업으로 지정하여 삭제됩니다.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}' } ], }"
부분 실패
단일 요청에 여러 작업이 있는 경우 선택적으로 partialFailure을 지정합니다. true인 경우 성공적인 작업이 실행되고 잘못된 작업은 오류를 반환합니다. false인 경우 요청의 모든 작업이 유효한 경우에만 성공합니다.
다음 예에서는 기존 캠페인을 사용합니다. Creates 예 출력에서 복사하여 붙여넣을 수 있습니다.
CAMPAIGN_ID=CAMPAIGN_ID다음 요청에는 두 개의 작업이 포함되어 있습니다. 첫 번째는 제공된 캠페인의 입찰 전략을 변경하려고 시도하고 다음은 잘못된 ID가 있는 캠페인을 삭제하려고 시도합니다. 두 번째 작업에서 오류가 발생하고 (캠페인 ID가 유효하지 않음) partialFailure이 false로 설정되어 있으므로 첫 번째 작업도 실패하고 기존 캠페인의 입찰 전략이 업데이트되지 않습니다.
curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'partialFailure': false, 'operations': [ { 'update': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}', 'manualCpc': { 'enhancedCpcEnabled': false } }, 'updateMask': 'manual_cpc.enhanced_cpc_enabled' }, { 'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID' } ] }"
그룹화된 작업
googleAds:mutate 메서드는 여러 유형의 리소스로 작업 그룹을 전송하는 것을 지원합니다. 다양한 유형의 작업을 많이 전송하여 그룹으로 실행해야 하는 작업 시퀀스를 연결할 수 있습니다.
작업이 실패하지 않으면 작업 집합이 성공하고 단일 작업이 실패하면 모두 실패합니다.
이 예에서는 캠페인 예산, 캠페인, 광고 그룹, 광고를 단일 작업 집합으로 함께 만드는 방법을 보여줍니다. 각 연속 작업은 이전 작업에 따라 달라집니다. 하나라도 실패하면 전체 작업 그룹이 실패합니다.
음수 정수 (-1, -2, -3)는 리소스 이름의 자리표시자로 사용되며 런타임에 작업 시퀀스의 결과로 동적으로 채워집니다.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'mutateOperations': [ { 'campaignBudgetOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'name': 'My Campaign Budget #${RANDOM}', 'deliveryMethod': 'STANDARD', 'amountMicros': 500000, 'explicitlyShared': false } } }, { 'campaignOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2', 'status': 'PAUSED', 'advertisingChannelType': 'SEARCH', 'geoTargetTypeSetting': { 'positiveGeoTargetType': 'PRESENCE_OR_INTEREST', 'negativeGeoTargetType': 'PRESENCE_OR_INTEREST' }, 'name': 'My Search campaign #${RANDOM}', 'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1', 'targetSpend': {} } } }, { 'adGroupOperation': { 'create': { 'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3', 'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2', 'name': 'My ad group #${RANDOM}', 'status': 'PAUSED', 'type': 'SEARCH_STANDARD' } } }, { 'adGroupAdOperation': { 'create': { 'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3', 'status': 'PAUSED', 'ad': { 'responsiveSearchAd': { 'headlines': [ { 'pinned_field': 'HEADLINE_1', 'text': 'An example headline' }, { 'text': 'Another example headline' }, { 'text': 'Yet another headline' } ], 'descriptions': [ { 'text': 'An example description' }, { 'text': 'Another example description' } ], 'path1': 'all-inclusive', 'path2': 'deals' }, 'finalUrls': ['https://www.example.com'] } } } } ] }"
계정 관리
계정을 만들고, 액세스 가능한 계정을 나열하고, 바이너리 애셋을 업로드할 수 있습니다.
계정 만들기
createCustomerClient 메서드를 사용하여 새 계정을 만듭니다. URL에는 고객 계정 ID가 아닌 관리자 계정 ID가 필요합니다. 관리자 계정 아래에 새 고객 계정이 생성됩니다.
curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'customerClient': { 'descriptiveName': 'My Client #${RANDOM}', 'currencyCode': 'USD', 'timeZone': 'America/New_York' } }"
액세스 가능한 계정 나열
간단한 GET 요청을 listAccessibleCustomers 메서드에 사용하여 지정된 OAuth 2.0 액세스 토큰으로 액세스할 수 있는 Google Ads 계정 목록을 가져옵니다. 이 요청에는 관리자 또는 클라이언트 계정 ID를 사용하면 안 됩니다.
curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
바이너리 애셋 업로드
assets:mutate 메서드는 애셋을 업로드하고 관리하는 데 사용됩니다. 이미지와 같은 바이너리 데이터는 패딩이 있는 표준 base64 인코딩을 사용하여 문자열로 인코딩됩니다. 패딩이 있거나 없는 표준 또는 URL 안전 base64 인코딩이 허용됩니다.
이 예시에서는 샘플을 간결하게 유지하기 위해 1픽셀 GIF를 인코딩합니다. 실제로 data 페이로드는 훨씬 더 큽니다.
base64 명령줄 유틸리티 (GNU 핵심 유틸리티의 일부)를 사용하여 1픽셀 GIF 이미지를 인코딩합니다.
base64 1pixel.gif
base64로 인코딩된 값은 API 요청에서 data 속성으로 지정됩니다.
curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \ --header "Content-Type: application/json" \ --header "developer-token: ${DEVELOPER_TOKEN}" \ --header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \ --header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \ --data "{ 'operations': [ { 'create': { 'name': 'My image asset #${RANDOM}', 'type': 'IMAGE', 'imageAsset': { 'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA' } } } ] }"