주의: 이 API의 REST 인터페이스에 대한 문서를 보고 있습니다. 대부분의 공식 클라이언트 라이브러리는 gRPC를 사용합니다. 자세한 내용은 REST 소개를 참조하세요.

이 페이지는 Cloud Translation API를 통해 번역되었습니다.

예

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

기본 요건

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

또한 개발자 토큰과 테스트 계정 액세스는 허용되며, 하나 이상의 고객 계정이 포함된 Google Ads 관리자 계정도 필요합니다.

환경 변수

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

API_VERSION="16"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

추가 객체 ID(선택사항)

다음 예 중 일부는 기존 예산 또는 캠페인에 대한 예입니다. 이 예에서 사용할 기존 객체의 ID가 있는 경우 아래에 ID를 입력하세요.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

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

검색

검색어 설명서 가이드에는 일부 기본 Google Ads 화면에 해당하고 이 가이드에서 사용된 동일한 환경 변수로 작동하는 여러 보고 샘플이 포함되어 있습니다. Google의 양방향 쿼리 빌더 도구도 대화형으로 커스텀 쿼리를 작성하기 위한 훌륭한 리소스입니다.

페이지 나눔

search 메서드는 query와 함께 지정된 조정 가능한 pageSize 매개변수와 함께 페이지로 나누기를 사용합니다.

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 '{
"pageSize": 10,
"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'
"
}'

Google 애널리틱스 QL

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

Google 애널리틱스 QL

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 배열을 채우면 여러 개의 변경 작업 (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인 경우 요청의 모든 작업이 모두 유효한 경우에만 성공합니다.

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

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

다른 방법

사용해 보기