Google menggunakan teknologi AI untuk menerjemahkan konten ke dalam bahasa pilihan Anda. Terjemahan AI mungkin mengandung kesalahan.

Mulai cepat

Panduan memulai cepat ini membantu Anda melakukan panggilan API pertama ke Google Ads API.

Konsep utama

Project Google Cloud: Project Google Cloud menjadi dasar untuk membuat, mengaktifkan, dan menggunakan semua layanan Google, termasuk mengelola API dan kredensial API OAuth 2.0. Anda dapat membuatnya dari Konsol Google Cloud.
Tingkat akses API: Tingkat akses API project Google Cloud Anda mengontrol jumlah panggilan API yang dapat Anda lakukan per hari dan lingkungan tempat Anda dapat melakukan panggilan API. Tingkat akses API project Anda tercantum di halaman Ringkasan Google Ads API project Anda.
Akun pengelola Google Ads: Akun pengelola Google Ads digunakan untuk mengelola akun Google Ads lainnya, yang dapat berupa kumpulan akun klien Google Ads atau akun pengelola Google Ads lainnya.
Akun klien Google Ads: Akun Google Ads yang digunakan untuk menjalankan iklan yang ingin Anda targetkan dengan panggilan API.
ID pelanggan klien: Nomor 10 digit yang mengidentifikasi akun klien Google Ads. Jika Anda menyalin ID ini dari UI Google Ads, pastikan untuk menghapus tanda hubung.
OAuth 2.0: OAuth 2.0 adalah protokol standar industri untuk otorisasi, yang digunakan oleh semua Google API. Anda memerlukan akun layanan dan kunci untuk membuat kredensial OAuth 2.0 guna melakukan panggilan API.
**Akun layanan:** Jenis Akun Google khusus milik aplikasi Anda, bukan milik pengguna individu. Akun ini digunakan untuk mengautentikasi aplikasi Anda ke Google Ads API. Anda memerlukan project Google Cloud untuk mendapatkan akun layanan.
Kunci akun layanan: File kredensial aplikasi JSON yang berisi kunci pribadi untuk akun layanan Anda. Kunci ini digunakan untuk membuat kredensial OAuth 2.0 guna mengautentikasi akun layanan saat melakukan panggilan Google Ads API. Anda memerlukan akun layanan untuk mendapatkan kunci akun layanan.

Prasyarat

Untuk melakukan panggilan Google Ads API, Anda harus menyelesaikan langkah-langkah berikut.

Mengonfigurasi project Cloud untuk akses Google Ads API

Project Google Cloud digunakan untuk mengelola Google API dan kredensial API OAuth 2.0. Anda dapat menemukan project Google Cloud yang ada atau membuat project baru dengan mengunjungi Konsol Google Cloud.

Mulailah dengan mengaktifkan Google Ads API di project Anda:

Mengaktifkan Google Ads API

Selanjutnya, buka halaman Ringkasan Google Ads API. Halaman ini menampilkan tingkat akses API Anda saat ini. Jika tingkat akses API Anda saat ini adalah Uji, luaskan bagian Tingkatkan tingkat akses. Ikuti petunjuk untuk mengajukan permohonan tingkat akses Explorer.

Setelah Anda menyelesaikan permohonan, Google akan otomatis meninjau permohonan Anda dan meningkatkan tingkat aksesnya ke Explorer pada sebagian besar kasus. Jika Anda tidak diberikan akses Explorer, jangan khawatir. Panduan ini akan memberikan petunjuk yang sesuai saat mengonfigurasi akun klien Google Ads Anda.

Membuat akun layanan

Anda memerlukan akun layanan dan kunci akun layanan untuk melakukan panggilan API. Jika Anda sudah menggunakan Google API lain dan telah membuat akun layanan dan kunci OAuth 2.0, Anda dapat melewati langkah ini dan menggunakan kembali kredensial yang ada.

Cara membuat akun layanan dan kunci

Di Konsol Google Cloud, buka Menu > IAM & Admin > Akun Layanan.
Buka Akun Layanan
Pilih akun layanan Anda.
Klik Kunci > Tambahkan kunci > Buat kunci baru.
Pilih JSON, lalu klik Buat.
Pasangan kunci umum/pribadi baru Anda dibuat dan didownload ke komputer Anda sebagai file baru. Simpan file JSON yang didownload sebagai credentials.json di direktori kerja Anda. File ini adalah satu-satunya salinan dari kunci ini. Jangan lakukan commit credentials.json ke kontrol versi (misalnya, tambahkan ke file .gitignore ).
Klik Tutup.

Mengonfigurasi akun klien Google Ads

Mulailah dengan mengidentifikasi akun Google Ads yang akan Anda gunakan untuk melakukan panggilan API. Jenis akun yang dapat Anda gunakan untuk melakukan panggilan API bergantung pada tingkat akses API project Google Cloud Anda. Periksa halaman ringkasan Google Ads API Anda untuk mengetahui tingkat akses API Anda.

Tingkat akses Explorer, Dasar, & Standar

Anda dapat melakukan panggilan ke akun produksi Google Ads Anda. Namun, Anda dapat membuat akun pengujian Google Ads dengan mengikuti petunjuk di tab Uji akses jika diperlukan.

Menguji akses

Project Google Cloud Anda tidak dapat digunakan untuk melakukan panggilan API ke akun produksi Google Ads. Anda hanya dapat melakukan panggilan API ke akun pengujian Google Ads.

Cara membuat akun pengujian Google Ads

Petunjuk berikut akan membuat akun pengelola pengujian Google Ads dan a akun pengiklan pengujian Google Ads di bawahnya.

Klik tombol biru untuk membuat akun pengelola pengujian Google Ads. Jika diminta, login dengan Akun Google yang tidak ditautkan ke akun pengelola produksi Google Ads Anda. Jika Anda tidak memilikinya, gunakan tombol Buat akun di halaman tersebut untuk membuat Akun Google baru.

Membuat akun pengelola pengujian Google Ads
Saat berada di akun pengelola pengujian Google Ads, buat akun pelanggan pengujian Google Ads: Klik Akun > > Buat akun baru dan isi formulir. Akun Google Ads yang Anda buat dari akun pengelola pengujian Google Ads akan otomatis menjadi akun pengujian Google Ads.
Secara opsional, buat beberapa kampanye di akun klien pengujian Google Ads dari halaman Google Ads.

Untuk melakukan panggilan API ke pelanggan Google Ads, Anda harus memberikan akses dan izin yang sesuai ke akun layanan Anda untuk akun pelanggan Google Ads. Untuk melakukannya, Anda memerlukan akses administrator ke akun pelanggan.

Cara memberikan akses akun layanan ke akun Google Ads Anda

Mulailah dengan login ke akun Google Ads Anda sebagai administrator.
Buka Admin > Akses dan keamanan.
Klik tombol di tab Pengguna.
Ketik alamat email akun layanan ke dalam kotak input Email. Pilih tingkat akses akun yang sesuai dan klik tombol Tambahkan akun. Perhatikan bahwa tingkat akses Email tidak didukung untuk akun layanan.
Akun layanan diberi akses.
[Opsional] Anda tidak dapat memberikan akses administrator ke akun layanan selama penyiapan awal. Jika panggilan API Anda memerlukan akses administrator akses, Anda dapat meningkatkan aksesnya sebagai berikut.
1. Klik panah drop-down di samping tingkat akses akun layanan di kolom Tingkat akses.
2. Pilih Admin dari menu drop-down.

Mendownload alat dan library klien

Anda dapat memilih untuk mendownload library klien atau klien HTTP, bergantung pada cara Anda ingin melakukan panggilan API.

Menggunakan library klien

Download dan instal library klien pilihan Anda.

Menggunakan klien HTTP (REST)

curl

Download dan instal curl, alat command line untuk mentransfer data melalui URL.

Google Cloud Command Line Interface

Ikuti panduan pemasangan Google Cloud CLI untuk menginstal gcloud CLI.

Petunjuk untuk bagian panduan ini lainnya telah diverifikasi agar berfungsi dengan versi alat gcloud berikut dan mungkin tidak berfungsi dengan versi sebelumnya karena perbedaan dalam perilaku aplikasi atau opsi command line.

:~$ gcloud version
Google Cloud SDK 492.0.0
alpha 2024.09.06
beta 2024.09.06
bq 2.1.8
bundled-python3-unix 3.11.9
core 2024.09.06
enterprise-certificate-proxy 0.3.2
gcloud-crc32c 1.0.0
gsutil 5.30

Melakukan panggilan API

Pilih klien pilihan Anda untuk mendapatkan petunjuk tentang cara melakukan panggilan API:

Java

Artefak library klien dipublikasikan ke repositori Maven Central.

Untuk mengelola versi dependensi dan mencegah konflik, lihat panduan Bill of Materials (BOM) Google Ads API.

Jika Anda tidak menggunakan BOM, tambahkan library klien langsung ke project Anda menggunakan salah satu alat build berikut:

Maven: Tambahkan dependensi berikut ke file pom.xml Anda:

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>google-ads</artifactId>
  <version>48.0.0</version>
</dependency>

Gradle: Tambahkan dependensi berikut ke file build.gradle Anda:

implementation 'com.google.api-ads:google-ads:48.0.0'

Buat file ads.properties di direktori utama Anda (~/ads.properties di Linux dan macOS, atau %USERPROFILE%\ads.properties di Windows) dengan konten berikut:

api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Sebelum menjalankan permintaan API, buat instance GoogleAdsClient. Secara default, fromPropertiesFile() memuat kredensial dari file ads.properties yang terletak di direktori utama Anda:

GoogleAdsClient googleAdsClient;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (IOException e) {
  System.err.printf("Failed to create GoogleAdsClient: %s%n", e);
  throw new RuntimeException("Initialization failed", e);
}

Selanjutnya, jalankan laporan kampanye menggunakan GoogleAdsService.SearchStream untuk melakukan streaming kumpulan hasil besar secara efisien dan mengambil kampanye di akun Anda:

    private void runExample(GoogleAdsClient googleAdsClient, long customerId) {
  try (GoogleAdsServiceClient googleAdsServiceClient =
      googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) {
    String query = "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id";
    // Constructs the SearchGoogleAdsStreamRequest.
    SearchGoogleAdsStreamRequest request =
        SearchGoogleAdsStreamRequest.newBuilder()
            .setCustomerId(Long.toString(customerId))
            .setQuery(query)
            .build();

    // Creates and issues a search Google Ads stream request that will retrieve all campaigns.
    ServerStream<SearchGoogleAdsStreamResponse> stream =
        googleAdsServiceClient.searchStreamCallable().call(request);

    // Iterates through and prints all of the results in the stream response.
    for (SearchGoogleAdsStreamResponse response : stream) {
      for (GoogleAdsRow googleAdsRow : response.getResultsList()) {
        System.out.printf(
            "Campaign with ID %d and name '%s' was found.%n",
            googleAdsRow.getCampaign().getId(), googleAdsRow.getCampaign().getName());
      }
    }
  }
}GetCampaigns.java

C#

Paket library klien dipublikasikan ke repositori NuGet.org. Mulailah dengan menambahkan referensi paket NuGet ke paket Google.Ads.GoogleAds:

dotnet add package Google.Ads.GoogleAds --version 27.5.0

Untuk melakukan panggilan API, buat objek GoogleAdsConfig dari setelan konfigurasi Anda (seperti appsettings.json, variabel lingkungan, atau setelan kustom) dan teruskan untuk melakukan inisialisasi instance GoogleAdsClient:

GoogleAdsConfig config = new GoogleAdsConfig()
{
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "JSON_KEY_FILE_PATH",
    LoginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"
};
GoogleAdsClient client = new GoogleAdsClient(config);

Selanjutnya, jalankan laporan kampanye menggunakan metode GoogleAdsService.SearchStream untuk mengambil kampanye di akun Anda. Panduan ini tidak membahas detail pelaporan.

    public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.GoogleAdsService);

    // Create a query that will retrieve all campaigns.
    string query = @"SELECT
                    campaign.id,
                    campaign.name,
                    campaign.network_settings.target_content_network
                FROM campaign
                ORDER BY campaign.id";

    try
    {
        // Issue a search request.
        googleAdsService.SearchStream(customerId.ToString(), query,
            delegate (SearchGoogleAdsStreamResponse resp)
            {
                foreach (GoogleAdsRow googleAdsRow in resp.Results)
                {
                    Console.WriteLine("Campaign with ID {0} and name '{1}' was found.",
                        googleAdsRow.Campaign.Id, googleAdsRow.Campaign.Name);
                }
            }
        );
    }
    catch (GoogleAdsException e)
    {
        Console.WriteLine("Failure:");
        Console.WriteLine($"Message: {e.Message}");
        Console.WriteLine($"Failure: {e.Failure}");
        Console.WriteLine($"Request ID: {e.RequestId}");
        throw;
    }
}GetCampaigns.cs

PHP

Paket library klien dipublikasikan ke repositori Packagist. Pastikan Anda telah menginstal Composer dan memiliki versi PHP yang kompatibel, lalu ubah ke direktori utama project Anda dan jalankan perintah berikut untuk menginstal library dan dependensinya di direktori vendor/ project Anda:

composer require googleads/google-ads-php:35.2.0

Buat salinan google_ads_php.ini file dari repositori GitHub, simpan di direktori utama atau direktori utama project Anda, dan ubah untuk menyertakan kredensial Anda:

[GOOGLE_ADS]
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

[OAUTH2]
jsonKeyFilePath = "JSON_KEY_FILE_PATH"
scopes = "https://www.googleapis.com/auth/adwords"

Buat instance GoogleAdsClient menggunakan file konfigurasi google_ads_php.ini Anda:

use Google\Ads\GoogleAds\Lib\OAuth2TokenBuilder;
use Google\Ads\GoogleAds\Lib\V26\GoogleAdsClientBuilder;

$oauth2Credential = (new OAuth2TokenBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->build();

$googleAdsClient = (new GoogleAdsClientBuilder())
    ->fromFile('/path/to/google_ads_php.ini')
    ->withOAuth2Credential($oauth2Credential)
    ->build();

Selanjutnya, jalankan laporan kampanye menggunakan metode GoogleAdsService.SearchStream untuk mengambil kampanye di akun Anda:

    public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId)
{
    $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient();
    // Creates a query that retrieves all campaigns.
    $query = 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id';
    // Issues a search stream request.
    /** @var GoogleAdsServerStreamDecorator $stream */
    $stream = $googleAdsServiceClient->searchStream(
        SearchGoogleAdsStreamRequest::build($customerId, $query)
    );

    // Iterates over all rows in all messages and prints the requested field values for
    // the campaign in each row.
    foreach ($stream->iterateAllElements() as $googleAdsRow) {
        /** @var GoogleAdsRow $googleAdsRow */
        printf(
            "Campaign with ID %d and name '%s' was found.%s",
            $googleAdsRow->getCampaign()->getId(),
            $googleAdsRow->getCampaign()->getName(),
            PHP_EOL
        );
    }
}GetCampaigns.php

Python

Library klien Google Ads API untuk Python didistribusikan di PyPI. Pastikan Anda telah menginstal versi Python yang didukung, lalu instal library menggunakan pip:

python -m pip install google-ads==34.0.0

Untuk mengautentikasi panggilan API Anda, konfigurasikan file google-ads.yaml:

Download salinan file contoh google-ads.yaml dari repositori GitHub.
Simpan file di direktori utama Anda (~/google-ads.yaml) atau jalur kustom.
Buka google-ads.yaml dan perbarui untuk menyertakan kredensial Anda:
```
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH
```
Konfigurasikan logging sebelum melakukan inisialisasi klien agar library dapat menangkap peringatan inisialisasi atau konfigurasi. Contoh berikut mengonfigurasi logger library untuk menampilkan log INFO ke output standar (stdout):

import logging
import sys

logger = logging.getLogger("google.ads.googleads.client")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(sys.stdout))

Buat instance GoogleAdsClient dengan memanggil metode GoogleAdsClient.load_from_storage dan meneruskan jalur ke file google-ads.yaml Anda:

from google.ads.googleads.client import GoogleAdsClient

client = GoogleAdsClient.load_from_storage("path/to/google-ads.yaml")

Jika Anda menghilangkan argumen jalur, load_from_storage() akan menelusuri file konfigurasi di direktori utama Anda (~/google-ads.yaml) secara default.

Selanjutnya, jalankan laporan kampanye menggunakan metode GoogleAdsService.SearchStream untuk mengambil kampanye di akun Anda:

    def main(client: GoogleAdsClient, customer_id: str) -> None:
    ga_service: GoogleAdsServiceClient = client.get_service("GoogleAdsService")

    query: str = """
        SELECT
          campaign.id,
          campaign.name
        FROM campaign
        ORDER BY campaign.id"""

    # Issues a search request using streaming.
    stream: Iterator[SearchGoogleAdsStreamResponse] = ga_service.search_stream(
        customer_id=customer_id, query=query
    )

    for batch in stream:
        rows: List[GoogleAdsRow] = batch.results
        for row in rows:
            print(
                f"Campaign with ID {row.campaign.id} and name "
                f'"{row.campaign.name}" was found.'
            )get_campaigns.py

Ruby

Gem Ruby untuk library klien dipublikasikan di RubyGems. Pastikan Anda telah menginstal versi Ruby yang didukung, dan gunakan Bundler untuk menginstal library:

Tambahkan gem ke Gemfile aplikasi Anda:

gem 'google-ads-googleads', '~> 46.0.0'

Instal gem dengan menjalankan:
```
bundle install
```

Untuk mengonfigurasi kredensial Anda:

Salin file google_ads_config.rb contoh dari repositori GitHub.
Simpan file di direktori utama project Anda atau direktori utama Anda (~).
Buka google_ads_config.rb dan ganti nilai placeholder dengan kredensial Google Ads API Anda:
```
Google::Ads::GoogleAds::Config.new do |c|
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end
```
Buat instance GoogleAdsClient dengan meneruskan jalur ke file konfigurasi Anda (google_ads_config.rb):

client = Google::Ads::GoogleAds::GoogleAdsClient.new(
  'path/to/google_ads_config.rb'
)

Selanjutnya, jalankan laporan kampanye menggunakan metode GoogleAdsService.SearchStream untuk mengambil kampanye di akun Anda:

    def get_campaigns(customer_id)
  # GoogleAdsClient will read a config file from
  # ENV['HOME']/google_ads_config.rb when called without parameters
  client = Google::Ads::GoogleAds::GoogleAdsClient.new

  responses = client.service.google_ads.search_stream(
    customer_id: customer_id,
    query: 'SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id',
  )

  responses.each do |response|
    response.results.each do |row|
      puts "Campaign with ID #{row.campaign.id} and name '#{row.campaign.name}' was found."
    end
  end
endget_campaigns.rb

Perl

Library klien Perl didistribusikan di CPAN dan memerlukan Perl 5.28 atau yang lebih tinggi dan pengelola paket cpan atau cpanm.

Clone repositori google-ads-perl di direktori pilihan Anda:

git clone https://github.com/googleads/google-ads-perl.git

Ubah ke direktori google-ads-perl dan jalankan perintah berikut untuk menginstal dependensi yang diperlukan dan membuat library:
```
cd google-ads-perl
cpan install Module::Build
perl Build.PL
perl Build installdeps
perl Build
perl Build install
```

Untuk mengonfigurasi kredensial Anda:

Salin file konfigurasi googleads.properties contoh dari repositori GitHub ke direktori utama Anda (~/googleads.properties):
```
cp googleads.properties ~/googleads.properties
```
Edit ~/googleads.properties untuk menyertakan kredensial Anda:
```
jsonKeyFilePath=JSON_KEY_FILE_PATH
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE
```
Buat instance Client dengan meneruskan jalur ke file googleads.properties yang dikonfigurasi (seperti ~/googleads.properties):

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => "/path/to/googleads.properties"
});

Selanjutnya, jalankan laporan kampanye menggunakan metode GoogleAdsService.SearchStream untuk mengambil kampanye di akun Anda:

    sub get_campaigns {
  my ($api_client, $customer_id) = @_;

  # Create a search Google Ads stream request that will retrieve all campaigns.
  my $search_stream_request =
    Google::Ads::GoogleAds::V26::Services::GoogleAdsService::SearchGoogleAdsStreamRequest
    ->new({
      customerId => $customer_id,
      query      =>
        "SELECT campaign.id, campaign.name FROM campaign ORDER BY campaign.id"
    });

  # Get the GoogleAdsService.
  my $google_ads_service = $api_client->GoogleAdsService();

  my $search_stream_handler =
    Google::Ads::GoogleAds::Utils::SearchStreamHandler->new({
      service => $google_ads_service,
      request => $search_stream_request
    });

  # Issue a search request and process the stream response to print the requested
  # field values for the campaign in each row.
  $search_stream_handler->process_contents(
    sub {
      my $google_ads_row = shift;
      printf "Campaign with ID %d and name '%s' was found.\n",
        $google_ads_row->{campaign}{id}, $google_ads_row->{campaign}{name};
    });

  return 1;
}get_campaigns.pl

Saat dijalankan, skrip akan melakukan streaming baris yang cocok dan mencetak ID serta nama setiap kampanye di akun Anda.

curl

Mulailah dengan menetapkan akun layanan sebagai kredensial aktif di gcloud CLI.

gcloud auth login --cred-file=JSON_KEY_FILE_PATH

Selanjutnya, ambil token akses OAuth 2.0 untuk Google Ads API.

gcloud auth \
  print-access-token \
  --scopes='https://www.googleapis.com/auth/adwords'

Buat file bernama query.json yang berisi permintaan Google Ads Query Language (GAQL) Anda:

{
  "query": "SELECT campaign.id, campaign.name, campaign.network_settings.target_content_network FROM campaign ORDER BY campaign.id"
}

Jalankan laporan kampanye menggunakan metode GoogleAdsService.SearchStream untuk mengambil kampanye di akun Anda:

curl -i -X POST \
  https://googleads.googleapis.com/v26/customers/CUSTOMER_ID/googleAds:searchStream \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "login-customer-id: LOGIN_CUSTOMER_ID" \
  --data-binary "@query.json"

Jika Anda mengalami error saat melakukan panggilan pertama, lihat Menangani error API untuk mendapatkan panduan tentang pemecahan masalah.

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

Konsep utama

Prasyarat

Mengonfigurasi project Cloud untuk akses Google Ads API

Membuat akun layanan

Cara membuat akun layanan dan kunci

Mengonfigurasi akun klien Google Ads

Tingkat akses Explorer, Dasar, & Standar

Menguji akses

Cara membuat akun pengujian Google Ads

Cara memberikan akses akun layanan ke akun Google Ads Anda

Mendownload alat dan library klien

Menggunakan library klien

Menggunakan klien HTTP (REST)

Melakukan panggilan API

Java

C#

PHP

Python

Ruby

Perl

curl

Mulai cepat