Caution: You are viewing documentation for the API's REST interface. Most of our official client libraries use gRPC. See the REST Introduction for details.

Contoh

Panduan ini berisi contoh panggilan endpoint REST secara langsung, tanpa menggunakan library klien.

Prasyarat

Semua contoh di bawah ini dimaksudkan agar mudah disalin dan ditempel ke shell bash menggunakan perintah curl.

Anda juga akan memerlukan token developer (akses akun pengujian) dan akun pengelola Google Ads yang berisi setidaknya satu akun klien.

Variabel lingkungan

Masukkan kredensial dan ID akun di bawah, lalu salin dan tempel ke terminal Anda untuk mengonfigurasi variabel lingkungan yang digunakan pada contoh berikutnya.

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

ID objek opsional tambahan

Beberapa contoh berikut berfungsi pada anggaran atau kampanye yang sudah ada sebelumnya. Jika Anda memiliki ID objek yang ada untuk digunakan dengan contoh ini, masukkan di bawah.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Jika tidak, kedua Mutate - Contoh pembuatan akan membuat anggaran dan kampanye baru.

Diberi halaman

Metode search menggunakan penomoran halaman, dengan parameter pageSize yang dapat disesuaikan yang ditentukan bersama query.

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

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'

Streaming

Metode searchStream men-streaming semua hasil dalam satu respons, sehingga kolom pageSize tidak didukung.

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'

Mutasi

Beberapa operasi mutasi (create, update, atau remove) dapat dikirim dalam isi permintaan JSON tunggal dengan mengisi array operations.

Membuat

Contoh ini membuat dua anggaran kampanye bersama dalam satu permintaan.

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

Contoh berikutnya menggunakan BUDGET_ID dari anggaran kampanye yang ada (Anda dapat menyalin dan menempelkan dari output langkah sebelumnya).

BUDGET_ID=BUDGET_ID

Resource yang merujuk ke resource lain melakukannya berdasarkan nama resource. Kampanye yang dibuat di bawah ini merujuk ke campaignBudget berdasarkan nama resource bernilai stringnya.

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

Mengupdate atribut objek yang ada menggunakan operasi update. Contoh berikutnya menggunakan kampanye yang ada (Anda dapat menyalin dan menempelkan dari langkah sebelumnya).

CAMPAIGN_ID=CAMPAIGN_ID

Semua update memerlukan kolom updateMask, yang merupakan daftar yang dipisahkan koma dari atribut JSON yang harus ada dalam permintaan yang harus diterapkan sebagai update. Atribut yang tercantum dalam updateMask, tetapi tidak ada dalam isi permintaan, akan dihapus pada objek. Atribut yang tidak tercantum di updateMask, tetapi ada di isi permintaan, akan diabaikan.

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

Hapus

Objek dihapus hanya dengan menentukan nama resource-nya sebagai operasi 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}'
  }
],
}"

Kegagalan sebagian

Jika beberapa operasi berada dalam satu permintaan, tentukan partialFailure secara opsional. Jika true, operasi yang berhasil akan dilakukan dan operasi yang tidak valid akan menampilkan error. Jika false, semua operasi dalam permintaan akan berhasil jika dan hanya jika semuanya valid.

Contoh berikutnya menggunakan kampanye yang ada (Anda dapat menyalin dan menempelkan dari output Creates).

CAMPAIGN_ID=CAMPAIGN_ID

Permintaan berikut berisi dua operasi. Upaya pertama untuk mengubah strategi bidding kampanye yang diberikan, dan yang berikutnya mencoba menghapus kampanye yang memiliki ID tidak valid. Karena operasi kedua menghasilkan error (ID kampanye tidak valid), dan karena partialFailure ditetapkan ke false, operasi pertama juga gagal, sehingga strategi bidding kampanye yang ada tidak diperbarui.

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

Operasi yang dikelompokkan

Metode googleAds:mutate mendukung pengiriman grup operasi dengan beberapa jenis resource. Anda dapat mengirim banyak operasi dari berbagai jenis untuk menyatukan urutan operasi yang harus dilakukan sebagai grup. Rangkaian operasi akan berhasil jika tidak ada operasi yang gagal atau semuanya gagal jika salah satu operasi gagal.

Contoh ini menunjukkan pembuatan anggaran kampanye, kampanye, grup iklan, dan iklan teks secara bersamaan sebagai satu kumpulan tindakan. Setiap operasi yang berurutan bergantung pada operasi sebelumnya. Jika salah satunya gagal, seluruh grup operasi akan gagal.

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': {
          'expandedTextAd': {
            'headlinePart1': 'An example headline1',
            'headlinePart2': 'An example headline2',
            'description': 'An example description'
          },
          'finalUrls': ['https://www.example.com']
        }
      }
    }
  }
]
}"

Pengelolaan akun

Membuat akun

Buat akun baru menggunakan metode createCustomerClient. Perhatikan bahwa URL tersebut memerlukan ID akun pengelola, bukan ID akun klien. Akun klien baru akan dibuat di bawah akun pengelola.

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

Mencantumkan akun yang dapat diakses

Gunakan permintaan GET sederhana ke metode listAccessibleCustomers untuk mendapatkan daftar akun Google Ads yang dapat diakses dengan token akses OAuth 2.0 yang diberikan. Perlu diketahui bahwa tidak ada ID akun klien atau pengelola yang boleh digunakan dalam permintaan ini.

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

Mengupload aset biner

Metode assets:mutate digunakan untuk mengupload dan mengelola Aset. Data biner, seperti gambar, dienkode sebagai string menggunakan encoding base64 standar dengan padding. Baik encoding standar atau URL yang aman untuk URL dengan/tanpa padding diterima.

Gunakan utilitas command line base64 (bagian dari utilitas inti GNU) untuk mengenkode gambar GIF 1 piksel.

base64 1pixel.gif

Nilai berenkode Base64 ditetapkan sebagai atribut data dalam permintaan API.

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