Contoh

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

Prasyarat

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

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

Penting: Dalam contoh ini, kami asumsikan bahwa Anda mengakses akun klien (CUSTOMER_ID) oleh pengguna yang memiliki akses admin ke akun pengelola (MANAGER_CUSTOMER_ID) yang mengelola akun klien secara langsung. Jika Anda alih-alih mengakses akun klien individu secara langsung, hilangkan Header login-customer-id atau tetapkan ke nilai yang sama dengan CUSTOMER_ID. Catatan beberapa contoh, seperti Membuat akun, memerlukan akun pengelola.

Variabel lingkungan

Masukkan kredensial dan ID akun di bawah ini, lalu salin dan tempel ke terminal untuk mengonfigurasi variabel lingkungan yang digunakan dalam contoh berikutnya. Panduan Otorisasi berisi 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 bersama contoh-contoh ini, masukkan di bawah ini.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

Jika tidak, kedua opsi Mutasi - Membuat contoh akan membuat anggaran baru dan kampanye.

Telusuri

Panduan Cookbook Kueri berisi banyak pelaporan contoh yang sesuai dengan beberapa layar Google Ads default dan berfungsi dengan variabel lingkungan yang sama yang digunakan dalam panduan ini. Kueri interaktif kami builder adalah juga merupakan sumber daya yang bagus untuk membangun kueri khusus 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'

Streaming

Metode searchStream mengalirkan semua hasil dalam satu respons, sehingga metode 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.

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 salin-dan-tempel dari {i>output<i} langkah sebelumnya.

BUDGET_ID=BUDGET_ID

Sumber daya yang merujuk pada sumber daya lain melakukannya dengan nama resource. Kampanye yang dibuat di bawah ini merujuk ke 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': {}
    }
  }
]
}"

Pembaruan

Perbarui atribut objek yang ada menggunakan operasi update. Berikutnya contoh menggunakan kampanye yang ada; Anda dapat menyalin-dan-menempel dari output langkah.

CAMPAIGN_ID=CAMPAIGN_ID

Semua pembaruan memerlukan {i>field<i} updateMask, daftar yang dipisahkan koma yang berisi atribut JSON mana yang harus ada dalam permintaan, yang harus diterapkan sebagai memperbarui. Atribut tercantum dalam updateMask tetapi tidak ada dalam permintaan body akan dihapus pada objek. Atribut 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 secara opsional partialFailure. 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 Membuat contoh.

CAMPAIGN_ID=CAMPAIGN_ID

Permintaan berikut berisi dua operasi. Upaya pertama untuk mengubah strategi bidding dari kampanye yang disediakan, dan yang berikutnya mencoba menghapus kampanye dengan ID yang tidak valid. Karena operasi kedua menghasilkan kesalahan ({i>error<i} yang ID kampanye tidak valid) dan karena partialFailure ditetapkan ke false, operasi pertama juga gagal dan strategi bidding kampanye yang ada akan 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 untuk berbagai jenis resource. Anda dapat mengirim banyak operasi dari berbagai jenis ke merangkai urutan operasi yang harus dilakukan sebagai satu kelompok. Rangkaian operasi berhasil jika tidak ada operasi yang gagal atau semuanya gagal jika ada jika hanya satu operasi akan gagal.

Contoh ini menunjukkan pembuatan anggaran kampanye, kampanye, grup iklan, dan iklan bersama sebagai serangkaian tindakan. Setiap operasi yang berurutan bergantung sebelumnya. Jika salah satunya gagal, seluruh grup operasi akan gagal.

Bilangan bulat negatif (-1, -2, -3) digunakan sebagai placeholder di resource dan diisi secara dinamis saat runtime dengan hasil dari urutan operasional bisnis.

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 memerlukan ID akun pengelola, bukan ID akun klien. 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 pengelola atau ID akun klien harus 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. Standar atau Encoding base64 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 GNU) 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'
      }
    }
  }
]
}"