Mulai cepat

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

Konsep utama

  • Token developer: Token developer adalah string alfanumerik, panjangnya 22 karakter, yang mengidentifikasi aplikasi Anda ke server Google Ads API. Diperlukan untuk melakukan panggilan API.
  • Tingkat akses API: Tingkat akses API token developer Anda mengontrol jumlah panggilan API yang dapat Anda lakukan per hari dan lingkungan tempat Anda dapat melakukan panggilan API.
  • Akun pengelola Google Ads: Akun pengelola Google Ads digunakan untuk mengelola akun Google Ads lainnya. Akun pengelola Google Ads dapat digunakan untuk mengelola akun klien Google Ads atau akun pengelola Google Ads lainnya. Anda memerlukan akun pengelola Google Ads untuk mendapatkan token developer.
  • Akun klien Google Ads: Akun Google Ads yang Anda gunakan untuk membuat panggilan API.
  • ID pelanggan klien: Nomor 10 digit yang mengidentifikasi akun klien Google Ads.
  • 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.
  • 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 Google Cloud Console.
  • Akun layanan: Jenis Akun Google khusus yang milik aplikasi Anda, bukan milik pengguna individual. Kunci 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. Kredensial 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.

Mendapatkan token Developer Anda

Jika pernah mendaftar untuk mendapatkan token developer sebelumnya, Anda dapat menemukannya dengan membuka Pusat API saat login ke akun pengelola Google Ads Anda.

Akses Pusat API

Jika tidak memiliki token developer, Anda dapat mendaftar untuk mendapatkannya di Pusat API.

Cara mendaftar untuk mendapatkan token developer

  1. Buka Pusat API di browser web Anda. Login ke akun pengelola Google Ads Anda jika diminta. Buat akun pengelola Google Ads jika Anda belum memilikinya.
  2. Isi formulir Akses API dan setujui Persyaratan dan Ketentuan.
    • Pastikan informasi Anda sudah benar dan URL situs perusahaan Anda berfungsi. Jika situs tidak aktif, Google mungkin tidak dapat memproses permohonan Anda dan menolaknya.
    • Pastikan email kontak API yang Anda berikan mengarah ke kotak masuk yang dipantau secara rutin. Tim kepatuhan API Google mungkin menghubungi alamat email ini selama proses peninjauan untuk meminta klarifikasi. Jika Anda tidak dapat dihubungi, Google mungkin tidak melanjutkan permohonan Anda.
    • Anda dapat mengedit email kontak API di Pusat API. Selalu perbarui informasi ini, bahkan setelah proses permohonan, agar Google dapat mengirimkan pengumuman layanan penting kepada Anda.

Setelah Anda menyelesaikan proses permohonan, token developer akan muncul di Pusat API Anda dengan status Menunggu Persetujuan. Token developer Anda kini memiliki tingkat Akses Akun Pengujian.

Mengonfigurasi project Konsol API Google

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

Buka Konsol Google API

Mulai dengan mengaktifkan Google Ads API di project Anda:

Aktifkan Google Ads API

Selanjutnya, 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.

  5. Klik Tutup.

Mulailah dengan mengidentifikasi akun Google Ads yang Anda gunakan untuk melakukan panggilan API. Jenis akun yang dapat Anda panggil API-nya bergantung pada tingkat Akses API token developer Anda. Periksa Pusat API Anda untuk mengetahui tingkat akses API Anda.

Akses Dasar & Standar

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

Akses Akun Pengujian

Token developer 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 Google Ads

Petunjuk berikut akan membuat akun pengelola pengujian Google Ads dan akun pengiklan Google Ads 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.

    Membuat 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 percobaan Google Ads akan otomatis menjadi akun percobaan Google Ads.
  3. Jika perlu, buat beberapa kampanye di akun klien uji 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.
  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.
  5. Akun layanan diberi akses.
  6. [Opsional] Secara default, Anda tidak dapat memberikan akses administrator ke akun layanan. 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 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 CLI

Ikuti petunjuk untuk menginstal gcloud CLI.

Petunjuk untuk bagian panduan ini telah diverifikasi agar berfungsi dengan alat gcloud versi berikut dan mungkin tidak berfungsi dengan versi sebelumnya karena perbedaan 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 pusat Maven. Tambahkan library klien sebagai dependensi ke project Anda sebagai berikut:

Dependensi Maven adalah:

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

Dependensi Gradle adalah:

implementation 'com.google.api-ads:google-ads:40.0.0'
api.googleads.serviceAccountSecretsPath=JSON_KEY_FILE_PATH
api.googleads.developerToken=INSERT_DEVELOPER_TOKEN_HERE
api.googleads.loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Buat objek GoogleAdsClient seperti berikut:

GoogleAdsClient googleAdsClient = null;
try {
  googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
} catch (FileNotFoundException fnfe) {
  System.err.printf(
      "Failed to load GoogleAdsClient configuration from file. Exception: %s%n",
      fnfe);
  System.exit(1);
} catch (IOException ioe) {
  System.err.printf("Failed to create GoogleAdsClient. Exception: %s%n", ioe);
  System.exit(1);
}

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

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 nuget ke paket Google.Ads.GoogleAds.

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

Buat objek GoogleAdsConfig dengan setelan yang relevan, lalu gunakan untuk membuat objek GoogleAdsClient.

GoogleAdsConfig config = new GoogleAdsConfig()
{
    DeveloperToken = "******",
    OAuth2Mode = OAuth2Flow.SERVICE_ACCOUNT,
    OAuth2SecretsJsonPath = "PATH_TO_CREDENTIALS_JSON",
    LoginCustomerId = ******
};
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.V21.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. Ubah ke direktori root project Anda dan jalankan perintah berikut untuk menginstal library dan semua dependensinya di direktori vendor/ pada direktori root project Anda.

composer require googleads/google-ads-php:31.0.0

Buat salinan file google_ads_php.ini dari repositori GitHub dan ubah untuk menyertakan kredensial Anda.

[GOOGLE_ADS]
developerToken = "INSERT_DEVELOPER_TOKEN_HERE"
loginCustomerId = "INSERT_LOGIN_CUSTOMER_ID_HERE"

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

Buat instance objek GoogleAdsClient.

$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. Panduan ini tidak membahas detail pelaporan.

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 didistribusikan di PyPI dapat diinstal menggunakan perintah pip sebagai berikut:

python -m pip install google-ads==21.3.0

Buat salinan file google-ads.yaml dari repositori GitHub dan ubah untuk menyertakan kredensial Anda.

developer_token: INSERT_DEVELOPER_TOKEN_HERE
login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE
json_key_file_path: JSON_KEY_FILE_PATH_HERE

Buat instance GoogleAdsClient dengan memanggil metode GoogleAdsClient.load_from_storage. Teruskan jalur ke google-ads.yaml Anda sebagai string ke metode saat memanggilnya:

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

Tambahkan pengendali ke logger pustaka yang memberi tahu tempat untuk mencetak log. Berikut akan memberi tahu logger library untuk mencetak ke konsol (stdout).

import logging
import sys

logger = logging.getLogger('google.ads.googleads.client')
logger.addHandler(logging.StreamHandler(sys.stdout))

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

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 ke situs hosting gem Rubygems. Cara yang direkomendasikan untuk menginstal adalah dengan menggunakan pemaket. Tambahkan baris ke Gemfile Anda:

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

Kemudian, jalankan:

bundle install

Buat salinan file google_ads_config.rb dari repositori GitHub dan ubah untuk menyertakan kredensial Anda.

Google::Ads::GoogleAds::Config.new do |c|
  c.developer_token = 'INSERT_DEVELOPER_TOKEN_HERE'
  c.login_customer_id = 'INSERT_LOGIN_CUSTOMER_ID_HERE'
  c.keyfile = 'JSON_KEY_FILE_PATH'
end

Buat instance GoogleAdsClient dengan meneruskan jalur ke tempat Anda menyimpan file ini.

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. Panduan ini tidak membahas detail pelaporan.

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 didistribusikan di CPAN. Mulai dengan meng-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 di command prompt untuk menginstal semua dependensi yang diperlukan untuk menggunakan library.

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

Buat salinan file googleads.properties dari repositori GitHub dan ubah untuk menyertakan kredensial Anda.

jsonKeyFilePath=JSON_KEY_FILE_PATH
developerToken=INSERT_DEVELOPER_TOKEN_HERE
loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HERE

Buat instance Client dengan meneruskan jalur ke tempat Anda menyimpan file ini.

my $properties_file = "/path/to/googleads.properties";

my $api_client = Google::Ads::GoogleAds::Client->new({
  properties_file => $properties_file
});

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

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::V21::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;
}

curl

Mulai dengan menyetel akun layanan sebagai kredensial aktif di gcloud CLI.

gcloud auth login --cred-file=PATH_TO_CREDENTIALS_JSON

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

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

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

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

Isi query.json adalah sebagai berikut:

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