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 perorangan. Kredensial 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. Metode 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 API Google dan kredensial API OAuth 2.0. Anda dapat menemukan project Google Cloud yang ada atau membuatnya dengan membuka Konsol Google Cloud.

Mulai dengan mengaktifkan Google Ads API di project Anda:

Aktifkan 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 mendaftar ke tingkat akses Penjelajah.

Setelah Anda menyelesaikan permohonan, Google akan otomatis meninjau permohonan Anda dan mengupgrade akun Anda ke Explorer pada sebagian besar kasus. Jika Anda tidak diberi 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

  1. Di Konsol Google Cloud, buka Menu > IAM & Admin > Service Accounts.

    Buka Akun Layanan

  2. Pilih akun layanan Anda.
  3. Klik Keys > Add key > Create new key.
  4. 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 kunci ini. Jangan commit credentials.json ke kontrol versi (misalnya, tambahkan ke file .gitignore Anda).

  5. Klik Tutup.

Mulailah dengan mengidentifikasi akun Google Ads yang 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 untuk mengetahui tingkat akses API Anda.

Tingkat akses Penjelajah, Dasar, dan Standar

Anda dapat melakukan panggilan ke akun produksi Google Ads. Namun, Anda dapat membuat akun uji Google Ads dengan mengikuti petunjuk di tab Akses pengujian 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 terhadap akun percobaan Google Ads.

Cara membuat akun uji coba Google Ads

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

  1. 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 belum memilikinya, gunakan tombol Buat akun di halaman tersebut untuk membuat Akun Google baru.

    Buat akun pengelola pengujian Google Ads

  2. Saat berada di akun pengelola pengujian Google Ads, buat akun pelanggan pengujian Google Ads: Klik Akun > > Buat akun baru dan isi formulir. Semua akun Google Ads yang Anda buat dari akun pengelola pengujian Google Ads akan otomatis menjadi akun pengujian Google Ads.
  3. Jika perlu, 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 memberi akun layanan akses ke akun Google Ads Anda

  1. Mulai dengan login ke akun Google Ads Anda sebagai administrator.
  2. Buka Admin > Akses dan keamanan.
  3. Klik tombol di tab Pengguna.
    Halaman Akses dan keamanan Google Ads yang menampilkan tombol tambahkan pengguna
  4. Ketik alamat email akun layanan ke dalam kotak input Email. Pilih tingkat akses akun yang sesuai, lalu klik tombol Tambahkan akun. Perhatikan bahwa tingkat akses Email tidak didukung untuk akun layanan.
    Dialog untuk menambahkan email akun layanan dan memilih tingkat akses
  5. Akun layanan diberi akses.
    Halaman akses dan keamanan yang menampilkan akun layanan dengan akses
  6. [Opsional] Anda tidak dapat memberikan akses administrator ke akun layanan selama penyiapan awal. Jika panggilan API Anda memerlukan akses administrator, Anda dapat mengupgrade akses sebagai berikut.
    1. Klik panah drop-down di samping tingkat akses akun layanan di kolom Tingkat akses.
    2. Pilih Admin dari daftar 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.

Antarmuka Command Line Google Cloud

Ikuti panduan penginstalan Google Cloud CLI untuk menginstal gcloud CLI.

Petunjuk untuk bagian panduan ini telah diverifikasi agar berfungsi dengan gcloud versi 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 mengetahui 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 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>46.1.0</version>
</dependency>

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

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

Buat file ads.properties di direktori beranda 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 ada di direktori beranda 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 set hasil yang 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());
      }
    }
  }
}

C#

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

dotnet add package Google.Ads.GoogleAds --version 27.4.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.V25.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;
    }
}

PHP

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

composer require googleads/google-ads-php:35.1.0

Buat salinan file google_ads_php.ini dari repositori GitHub, simpan di direktori beranda atau direktori root project Anda, lalu 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\V25\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
        );
    }
}

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==33.0.0

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

  1. Download salinan file contoh google-ads.yaml dari repositori GitHub.
  2. Simpan file di direktori beranda Anda (~/google-ads.yaml) atau jalur kustom.
  3. 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
    

    Konfigurasi logging sebelum melakukan inisialisasi klien agar library mencatat peringatan inisialisasi atau konfigurasi. Contoh berikut mengonfigurasi logger library untuk menghasilkan 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.'
            )

Ruby

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

  1. Tambahkan gem ke Gemfile aplikasi Anda:

    gem 'google-ads-googleads', '~> 45.1.0'
    
  2. Instal gem dengan menjalankan:

    bundle install

Untuk mengonfigurasi kredensial Anda:

  1. Salin file contoh google_ads_config.rb dari repositori GitHub.
  2. Simpan file di direktori root project atau direktori beranda Anda (~).
  3. 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
end

Perl

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

  1. Buat clone repositori google-ads-perl di direktori pilihan Anda:

    git clone https://github.com/googleads/google-ads-perl.git
  2. Buka direktori google-ads-perl dan jalankan perintah berikut untuk menginstal dependensi yang diperlukan dan membangun library:

    cd google-ads-perl
    cpan install Module::Build
    perl Build.PL
    perl Build installdeps
    perl Build
    perl Build install

Untuk mengonfigurasi kredensial Anda:

  1. Salin file konfigurasi contoh googleads.properties dari repositori GitHub ke direktori beranda Anda (~/googleads.properties):

    cp googleads.properties ~/googleads.properties
  2. 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::V25::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;
}

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

curl

Mulai dengan menyetel 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/v25/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.