Panduan ini berisi contoh panggilan endpoint REST secara langsung, tanpa menggunakan library klien.
Prasyarat
Semua contoh di bawah ini dimaksudkan untuk disalin dan ditempel ke shell bash menggunakan perintah curl.
Anda juga memerlukan token developer, Anda dapat menggunakan 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 dalam contoh berikutnya. Panduan Otorisasi memberikan petunjuk untuk membuat token akses 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 objek opsional tambahan
Beberapa contoh berikut berfungsi pada anggaran atau kampanye yang sudah ada sebelumnya. Jika Anda memiliki ID objek yang sudah ada untuk digunakan dengan contoh ini, masukkan ID tersebut di bawah.
BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID
Jika tidak, kedua contoh Mutasi - Membuat ini akan membuat anggaran dan kampanye baru.
Telusuri
Panduan Panduan Kueri berisi banyak contoh pelaporan yang sesuai dengan beberapa layar Google Ads default dan berfungsi dengan variabel lingkungan yang sama dengan yang digunakan dalam panduan ini. Alat pembuat kueri interaktif kami juga merupakan resource yang bagus untuk membuat kueri kustom secara interaktif.
Diberi halaman
Metode search
menggunakan penomoran halaman, dengan ukuran halaman tetap sebanyak 10.000 item dan
page_token
yang ditentukan di samping 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 '{ "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'
Perangkat streaming
Metode searchStream
mengalirkan 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
satu isi permintaan JSON dengan mengisi array operations
.
Kreasi
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 menempel dari output langkah sebelumnya.
BUDGET_ID=BUDGET_ID
Resource yang merujuk ke resource lain melakukannya dengan
nama resource. Kampanye yang dibuat di bawah
merujuk pada campaignBudget
berdasarkan nama resource bernilai string.
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': {} } } ] }"
Info terbaru
Perbarui atribut objek yang ada menggunakan operasi update
. Contoh berikutnya menggunakan kampanye yang sudah ada; Anda dapat menyalin dan menempelkan dari output langkah sebelumnya.
CAMPAIGN_ID=CAMPAIGN_ID
Semua update memerlukan kolom updateMask
, yaitu daftar yang dipisahkan koma yang berisi atribut JSON yang harus dicantumkan dalam permintaan dan diterapkan sebagai update. Atribut yang tercantum dalam updateMask
tetapi tidak ada dalam isi
permintaan akan dihapus pada objek. Atribut yang tidak tercantum dalam updateMask
, tetapi ada
dalam 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 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 contoh Buat.
CAMPAIGN_ID=CAMPAIGN_ID
Permintaan berikut berisi dua operasi. Percobaan pertama untuk mengubah strategi bidding di kampanye yang diberikan, dan percobaan berikutnya mencoba menghapus kampanye dengan ID yang tidak valid. Karena operasi kedua menghasilkan error (ID kampanye tidak valid) dan karena partialFailure
ditetapkan ke false
, operasi pertama juga akan gagal dan 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 berbagai jenis operasi untuk merangkai urutan operasi yang harus dilakukan sebagai satu kelompok.
Rangkaian operasi akan berhasil jika tidak ada operasi yang gagal, atau semuanya gagal jika ada satu operasi yang gagal.
Contoh ini menunjukkan pembuatan anggaran kampanye, kampanye, grup iklan, dan iklan secara bersamaan sebagai satu kumpulan tindakan. Setiap operasi yang berurutan bergantung pada operasi sebelumnya. Jika salah satunya gagal, seluruh grup operasi akan gagal.
Bilangan bulat negatif (-1
, -2
, -3
) digunakan sebagai placeholder dalam nama
resource dan diisi secara dinamis saat runtime dengan hasil dari urutan
operasi.
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'] } } } } ] }"
Pengelolaan akun
Membuat akun
Buat akun baru menggunakan metode createCustomerClient
. Perhatikan bahwa URL ini memerlukan ID akun pengelola, bukan ID akun klien. Akun klien baru 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. 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. Encoding base64 standar maupun
yang aman untuk URL dengan atau tanpa padding dapat diterima.
Contoh ini mengenkode GIF 1 piksel agar sampel tetap ringkas. Dalam praktiknya, payload data
jauh lebih besar.
Gunakan utilitas command line base64
(bagian dari
utilitas inti GCC)
untuk mengenkode gambar GIF 1 piksel.
base64 1pixel.gif
Nilai yang dienkode 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' } } } ] }"