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

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

예

이 가이드에는 사용할 수 있습니다

기본 요건

아래의 모든 샘플은 복사하여 bash 셸 curl 명령을 사용합니다.

또한 개발자 토큰이 필요합니다. test 계정 액세스는 문제가 없으며 Google Ads 관리자 계정에 하나 이상의 고객 계정이 포함되어 있습니다.

환경 변수

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

API_VERSION="17"
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 예시를 통해 새 예산이 생성됩니다. 살펴보겠습니다

검색

쿼리 설명서 가이드에는 다양한 보고 기능이 포함되어 있습니다. 샘플이 기본 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}"
}'

Google Cloud의 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'
"
}'

Google Cloud의 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'

변형

여러 개의 변형 연산 (create, update 또는 remove)을 operations 배열을 입력하여 단일 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

모든 업데이트에는 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 요청을 사용하여 목록 가져오기 모든 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'
      }
    }
  }
]
}"

다른 방법

사용해 보기