예

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

기본 요건

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

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

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

환경 변수

아래에 계정 사용자 인증 정보와 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'

변형

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

액세스 가능한 계정 나열

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