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.
Jika tidak memiliki token developer, Anda dapat mendaftar untuk mendapatkannya di Pusat API.
Cara mendaftar untuk mendapatkan token developer
- 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.
- 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.
Mulai dengan mengaktifkan Google Ads API di project Anda:
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
- 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.json
di direktori kerja Anda. File ini adalah satu-satunya salinan kunci ini. - 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 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.
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 percobaan Google Ads akan otomatis menjadi akun percobaan Google Ads.
- 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
- 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] Secara default, Anda tidak dapat memberikan akses administrator ke
akun layanan. 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 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"
}