예

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

기본 요건

아래의 모든 샘플은 curl 명령어를 사용하여 bash 셸에 복사하여 붙여넣을 수 있습니다.

개발자 토큰(테스트 계정 액세스도 가능)과 하나 이상의 고객 계정이 포함된 Google Ads 관리자 계정도 필요합니다.

중요: 이 예에서는 고객 계정을 직접 관리하는 관리자 계정(MANAGER_CUSTOMER_ID)에 대한 관리 액세스 권한이 있는 사용자가 고객 계정(CUSTOMER_ID)에 액세스한다고 가정합니다. 대신 개별 고객 계정에 직접 액세스하는 경우 login-customer-id 헤더를 생략하거나 CUSTOMER_ID와 동일한 값으로 설정합니다. 계정 만들기와 같은 일부 예시에는 관리자 계정이 필요합니다.

환경 변수

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

API_VERSION="19"
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

그렇지 않으면 두 개의 변경 - 예시 만들기가 새 예산과 캠페인을 만듭니다.

검색

쿼리 레시피 가이드에는 일부 기본 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 배열을 채우면 단일 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

모든 업데이트에는 updateMask 필드가 필요합니다. 이 필드는 요청에 있어야 하는 JSON 속성의 쉼표로 구분된 목록으로, 업데이트로 적용되어야 합니다. 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인 경우 요청의 모든 작업이 모두 유효한 경우에만 성공합니다.

다음 예에서는 기존 캠페인을 사용합니다. 만들기 예시 출력에서 복사하여 붙여넣을 수 있습니다.

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'
}
}"

액세스 가능한 계정 나열

listAccessibleCustomers 메서드에 대한 간단한 GET 요청을 사용하여 지정된 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'
      }
    }
  }
]
}"