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:
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
- Di Konsol Google Cloud, buka Menu > IAM & Admin > Service Accounts.
- Pilih akun layanan Anda.
- Klik Keys > Add key > Create new key.
- 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.jsondi direktori kerja Anda. File ini adalah satu-satunya salinan kunci ini. Jangan commitcredentials.jsonke kontrol versi (misalnya, tambahkan ke file.gitignoreAnda). - Klik Tutup.
Mengonfigurasi akun klien Google Ads Anda
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.
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.
- 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.
- 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
- Mulai 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, lalu 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, Anda dapat mengupgrade akses sebagai berikut.
- Klik panah drop-down di samping tingkat akses akun layanan di kolom Tingkat akses.
- 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.30Melakukan 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.0Untuk 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.0Buat 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.0Untuk mengautentikasi panggilan API, konfigurasi file google-ads.yaml:
- Download salinan file contoh
google-ads.yamldari repositori GitHub. - Simpan file di direktori beranda Anda (
~/google-ads.yaml) atau jalur kustom. Buka
google-ads.yamldan perbarui untuk menyertakan kredensial Anda:login_customer_id: INSERT_LOGIN_CUSTOMER_ID_HERE json_key_file_path: JSON_KEY_FILE_PATHKonfigurasi logging sebelum melakukan inisialisasi klien agar library mencatat peringatan inisialisasi atau konfigurasi. Contoh berikut mengonfigurasi logger library untuk menghasilkan log
INFOke 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:
Tambahkan gem ke
Gemfileaplikasi Anda:gem 'google-ads-googleads', '~> 45.1.0'Instal gem dengan menjalankan:
bundle install
Untuk mengonfigurasi kredensial Anda:
- Salin file contoh
google_ads_config.rbdari repositori GitHub. - Simpan file di direktori root project atau direktori beranda Anda
(
~). Buka
google_ads_config.rbdan 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' endBuat instance
GoogleAdsClientdengan 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.
Buat clone repositori
google-ads-perldi direktori pilihan Anda:git clone https://github.com/googleads/google-ads-perl.gitBuka direktori
google-ads-perldan 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:
Salin file konfigurasi contoh
googleads.propertiesdari repositori GitHub ke direktori beranda Anda (~/googleads.properties):cp googleads.properties ~/googleads.propertiesEdit
~/googleads.propertiesuntuk menyertakan kredensial Anda:jsonKeyFilePath=JSON_KEY_FILE_PATH loginCustomerId=INSERT_LOGIN_CUSTOMER_ID_HEREBuat instance
Clientdengan meneruskan jalur ke filegoogleads.propertiesyang 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_PATHSelanjutnya, 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.