Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

예

이 가이드에는 클라이언트 라이브러리를 사용하지 않고 REST 엔드포인트를 직접 호출하는 예가 포함되어 있습니다.

자세한 코드 예는 REST 코드 예 GitHub 저장소를 참고하세요.

각 API 메서드의 요청 및 응답 본문을 보려면 특정 서비스 엔드포인트의 참조 문서를 참고하세요.

예를 들어 참조 페이지 GoogleAdsService.Search의 요청 및 응답 본문이 Search 메서드에 표시됩니다.

기본 요건

여기에 표시된 모든 샘플은 bash shell에 복사하여 붙여넣을 수 있습니다. curl 명령어를 사용합니다.

또한 개발자 토큰, 테스트 계정 액세스 권한이 필요하며 클라이언트 계정이 하나 이상 포함된 Google Ads 관리자 계정도 필요합니다.

환경 변수

표시된 대로 계정 사용자 인증 정보와 ID를 입력한 다음 터미널에 복사하여 붙여넣어 후속 예에서 사용되는 환경 변수를 구성합니다. 승인 가이드에서는 OAuth 2.0 액세스 토큰을 생성하는 방법을 안내합니다.

API_VERSION="25"
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 예에서 새 예산 과 캠페인을 만듭니다.

검색

쿼리 Cookbook 가이드에는 일부 기본 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'

스트리밍

searchStream 메서드는 모든 결과를 단일 응답으로 스트리밍하므로 pageSize 필드는 지원되지 않습니다.

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'

Mutates

operations 배열을 채워 여러 변경 작업 (create, update 또는 remove)을 단일 JSON 요청 본문으로 보낼 수 있습니다.

생성

이 예에서는 단일 요청으로 두 개의 공유 캠페인 예산을 만듭니다.

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 core utilities의 일부)를 사용하여 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'
      }
    }
  }
]
}"

일반적인 오류

사용해 보기

예 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

기본 요건

환경 변수

추가 선택적 객체 ID

검색

페이지 나눔

curl

GAQL

스트리밍

curl

GAQL

Mutates

생성

업데이트

삭제

부분 실패

그룹화된 작업

계정 관리

계정 만들기

액세스 가능 계정 나열

바이너리 애셋 업로드

예