Perhatian: Anda sedang melihat dokumentasi untuk antarmuka REST API. Sebagian besar library klien resmi kami menggunakan gRPC. Lihat Pengantar REST untuk mengetahui detailnya.

Halaman ini diterjemahkan oleh Cloud Translation API.

Contoh

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

Prasyarat

Semua contoh yang ditampilkan di sini dimaksudkan untuk disalin dan ditempelkan ke bash shell menggunakan perintah curl.

Anda juga memerlukan token developer, akses akun pengujian tidak masalah, dan akun pengelola Google Ads yang berisi minimal satu akun klien.

Variabel lingkungan

Masukkan kredensial dan ID akun seperti yang ditunjukkan, lalu salin dan tempel ke terminal untuk mengonfigurasi variabel lingkungan yang digunakan dalam contoh berikutnya. Panduan Otorisasi memberikan petunjuk untuk membuat token akses OAuth 2.0.

API_VERSION="20"
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. Jika Anda memiliki ID objek yang ada untuk digunakan dengan contoh ini, masukkan ID tersebut seperti yang ditunjukkan.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Jika tidak, dua Mutasi - Contoh pembuatan akan membuat anggaran dan kampanye baru.

Telusuri

Panduan Query Cookbook berisi banyak contoh pelaporan yang sesuai dengan beberapa layar default Google Ads dan berfungsi dengan variabel lingkungan yang sama yang digunakan dalam panduan ini. Alat pembuat kueri interaktif kami juga merupakan sumber yang bagus untuk membuat kueri kustom secara interaktif.

Berhalaman

Metode search menggunakan penomoran halaman, dengan ukuran halaman tetap 10.000 item dan page_token yang ditentukan bersama dengan 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'

### Streaming Metode `searchStream` melakukan 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'

Mengubah

Beberapa operasi perubahan (create, update, atau remove) dapat dikirim dalam satu isi permintaan JSON 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 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 dalam contoh berikut merujuk ke campaignBudget berdasarkan nama resource bernilai string-nya.

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

Perbarui atribut objek yang ada menggunakan operasi update. Contoh berikutnya menggunakan kampanye yang ada; Anda dapat menyalin dan menempelkan dari output langkah sebelumnya.

CAMPAIGN_ID=CAMPAIGN_ID

Semua pembaruan memerlukan kolom updateMask, daftar yang dipisahkan koma dari atribut JSON yang harus ada dalam permintaan, yang harus diterapkan sebagai pembaruan. Atribut yang tercantum dalam updateMask tetapi tidak ada dalam isi permintaan 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 ada beberapa operasi 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 berhasil jika dan hanya jika semuanya valid.

Contoh berikutnya menggunakan kampanye yang ada; Anda dapat menyalin dan menempel dari output contoh Membuat.

CAMPAIGN_ID=CAMPAIGN_ID

Permintaan berikut berisi dua operasi. Yang pertama mencoba mengubah strategi bidding kampanye yang diberikan, dan yang 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 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 banyak operasi dari berbagai jenis untuk merangkai urutan operasi yang harus dilakukan sebagai satu grup. Serangkaian operasi berhasil jika tidak ada operasi yang gagal atau semua operasi gagal jika ada satu operasi yang gagal.

Contoh ini menunjukkan cara membuat anggaran kampanye, kampanye, grup iklan, dan iklan bersama-sama sebagai satu set tindakan. Setiap operasi berikutnya bergantung pada operasi sebelumnya. Jika salah satu 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

Anda dapat membuat akun, mencantumkan akun yang dapat diakses, dan mengupload aset biner.

Buat akun

Buat akun baru menggunakan metode createCustomerClient. Perhatikan bahwa URL memerlukan ID akun pengelola, bukan ID akun klien. Akun klien baru dibuat di 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 pengelola atau klien 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 atau yang sesuai untuk URL dengan atau tanpa padding diterima.

Contoh ini mengenkode GIF 1 piksel agar contoh tetap ringkas. Dalam praktiknya, payload data jauh lebih besar.

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

base64 1pixel.gif

Nilai berenkode base64 ditentukan 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'
      }
    }
  }
]
}"

Sebelumnya

Metode lainnya

Contoh Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Prasyarat

Variabel lingkungan

ID objek opsional tambahan

Telusuri

Berhalaman

curl

GAQL

curl

GAQL

Mengubah

Membuat

Update

Hapus

Kegagalan sebagian

Operasi yang dikelompokkan

Pengelolaan akun

Buat akun

Mencantumkan akun yang dapat diakses

Mengupload aset biner

Contoh