Fitur canggih skrip Google Ads adalah kemampuan untuk berintegrasi dengan data dan layanan dari API pihak ketiga.
Panduan ini membahas konsep berikut yang dapat membantu Anda menulis skrip untuk terhubung ke layanan lain:
- Membuat permintaan HTTP: Cara menggunakan
UrlFetchApp
untuk mengakses API eksternal. - Autentikasi: Kita membahas beberapa skenario autentikasi umum.
- Menguraikan respons: Cara memproses data JSON dan XML yang ditampilkan.
Mengambil data dengan UrlFetchApp
UrlFetchApp
menyediakan
fungsi inti yang diperlukan untuk berinteraksi dengan API pihak ketiga.
Contoh berikut menunjukkan pengambilan data cuaca dari OpenWeatherMap. Kami memilih OpenWeatherMap karena skema otorisasi dan API yang relatif sederhana.
Buat permintaan
Dokumentasi OpenWeatherMap menentukan format untuk meminta cuaca saat ini sebagai berikut:
http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]
URL tersebut memberikan contoh otorisasi pertama kami: Parameter apikey
diperlukan, dan nilainya unik untuk setiap pengguna. Kunci ini diperoleh melalui
mendaftar.
Setelah pendaftaran, permintaan menggunakan kunci tersebut dapat diajukan sebagai berikut:
const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());
Mengeksekusi kode ini akan menghasilkan string panjang teks JSON yang ditulis ke jendela logging dalam skrip Google Ads.
Langkah selanjutnya adalah mengonversinya ke format yang dapat digunakan dalam skrip Anda.
Data JSON
Banyak API memberikan respons dalam format JSON. Hal ini mewakili serialisasi sederhana objek JavaScript, sehingga objek, array, dan jenis dasar dapat direpresentasikan dan ditransfer sebagai string.
Untuk mengonversi string JSON, seperti string yang ditampilkan dari OpenWeatherMap, kembali menjadi objek JavaScript, gunakan metode JSON.parse
bawaan. Melanjutkan dari contoh di atas:
const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
// "London"
Metode JSON.parse
mengonversi string menjadi objek, yang memiliki properti
name
.
Baca bagian Respons penguraian untuk mengetahui detail lebih lanjut tentang cara menggunakan respons API dalam berbagai format.
Penanganan error
Penanganan error adalah pertimbangan penting saat bekerja dengan API pihak ketiga dalam skrip karena API pihak ketiga sering berubah dan menghasilkan nilai respons yang tidak terduga, misalnya:
- URL atau parameter untuk API dapat berubah tanpa sepengetahuan Anda.
- Masa berlaku kunci API Anda (atau kredensial pengguna lainnya) dapat berakhir.
- Format respons dapat berubah tanpa pemberitahuan.
Kode status HTTP
Karena adanya potensi respons yang tidak terduga, Anda harus memeriksa kode status HTTP. Secara default, UrlFetchApp
akan menampilkan pengecualian jika kode error HTTP ditemukan. Untuk
mengubah perilaku ini, Anda perlu meneruskan parameter opsional, seperti dalam
contoh berikut:
const options = {
muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
// Error encountered, send an email alert to the developer
sendFailureEmail();
}
Struktur respons
Saat API pihak ketiga berubah, developer sering kali tidak segera mengetahui
perubahan yang mungkin memengaruhi skrip mereka. Misalnya, jika properti name
yang ditampilkan dalam contoh OpenWeatherMap diubah menjadi locationName
, skrip yang menggunakan properti ini akan gagal.
Oleh karena itu, akan bermanfaat untuk menguji apakah struktur yang ditampilkan seperti yang diharapkan, misalnya:
const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
console.log('Location is : ' + name);
} else {
console.log('Data not in expected format');
}
Data POST dengan UrlFetchApp
Contoh pengantar dengan OpenWeatherMap hanya mengambil data. Biasanya, panggilan API yang tidak mengubah status di server
jarak jauh menggunakan metode
HTTP
GET
.
Metode GET
adalah default untuk UrlFetchApp
. Namun, beberapa panggilan API, seperti panggilan ke layanan yang mengirimkan pesan SMS, akan memerlukan metode lain, seperti POST
atau PUT
.
Untuk menggambarkan penggunaan panggilan POST
dengan UrlFetchApp
, contoh berikut
menunjukkan integrasi dengan Slack, sebuah aplikasi pesan
kolaboratif, untuk mengirim pesan Slack kepada pengguna dan grup Slack.
Menyiapkan Slack
Panduan ini mengasumsikan bahwa Anda telah mendaftar untuk akun Slack.
Seperti OpenWeatherMap di contoh sebelumnya, Anda perlu mendapatkan token untuk mengaktifkan pengiriman pesan. Slack menyediakan URL unik yang memungkinkan Anda mengirim pesan ke tim, yang disebut Webhook Masuk.
Siapkan Webhook Masuk dengan mengklik Add Incoming WebHooks Integration dan mengikuti petunjuknya. Proses ini akan menerbitkan URL yang akan digunakan untuk pengiriman pesan.
Membuat permintaan POST
Setelah menyiapkan Webhook Masuk, pembuatan permintaan POST
hanya memerlukan
penggunaan beberapa properti tambahan dalam parameter options
yang diteruskan ke
UrlFetchApp.fetch
:
method
: Seperti yang telah disebutkan, nilai defaultnya adalahGET
, tetapi di sini kita menggantinya dan menetapkannya kePOST
.payload
: Ini adalah data yang akan dikirim ke server sebagai bagian dari permintaanPOST
. Dalam contoh ini, Slack mengharapkan objek yang diserialisasi ke format JSON seperti yang dijelaskan dalam dokumentasi Slack. Untuk itu, metodeJSON.stringify
digunakan, danContent-Type
disetel keapplication/json
.// Change the URL for the one issued to you from 'Setting up Slack'. const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC'; const slackMessage = { text: 'Hello, slack!' }; const options = { method: 'POST', contentType: 'application/json', payload: JSON.stringify(slackMessage) }; UrlFetchApp.fetch(SLACK_URL, options);
Contoh Slack yang diperluas
Contoh di atas menunjukkan jumlah minimum untuk mengaktifkan pesan masuk ke Slack. Contoh tambahan menggambarkan pembuatan dan pengiriman Laporan Performa Kampanye ke grup, serta beberapa opsi format dan tampilan.
Lihat pemformatan pesan dalam dokumentasi Slack untuk mengetahui detail selengkapnya tentang pesan Slack.
Data formulir
Contoh di atas menunjukkan penggunaan string JSON sebagai properti payload
untuk permintaan POST
.
Bergantung pada format payload
, UrlFetchApp
menggunakan pendekatan yang berbeda
untuk membuat permintaan POST
:
- Jika
payload
adalah string, argumen string akan dikirim sebagai isi permintaan. Jika
payload
adalah objek, misalnya peta nilai:{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
Key-value pair dikonversi menjadi data formulir:
subject=Test&to=mail@example.com&body=Hello,+World!
Selain itu, header
Content-Type
untuk permintaan ditetapkan keapplication/x-www-form-urlencoded
.
Beberapa API memerlukan penggunaan data formulir saat mengirimkan permintaan POST, sehingga konversi otomatis dari objek JavaScript ke data formulir ini berguna untuk diingat.
Autentikasi dasar HTTP
Autentikasi dasar HTTP adalah salah satu bentuk autentikasi paling sederhana dan digunakan oleh banyak API.
Autentikasi dilakukan dengan melampirkan nama pengguna dan sandi yang dienkode ke header HTTP dalam setiap permintaan.
Membuat permintaan
Langkah-langkah berikut diperlukan untuk menghasilkan permintaan terautentikasi:
- Susun frasa sandi dengan menggabungkan nama pengguna dan sandi dengan titik dua, misalnya
username:password
. - Base64 mengenkode frasa sandi, misalnya
username:password
menjadidXNlcm5hbWU6cGFzc3dvcmQ=
. - Lampirkan header
Authorization
ke permintaan, dalam bentukAuthorization: Basic <encoded passphrase>
Cuplikan berikut menggambarkan cara melakukannya di Skrip Google Ads:
const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';
const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);
Plivo
Plivo adalah layanan yang memfasilitasi pengiriman dan penerimaan pesan SMS melalui API-nya. Contoh ini mengilustrasikan pengiriman pesan.
- Daftar ke Plivo.
- Tempelkan skrip contoh ke skrip baru di Google Ads.
- Ganti nilai
PLIVO_ACCOUNT_AUTHID
danPLIVO_ACCOUNT_AUTHTOKEN
dengan nilai dari dasbor pengelolaan. - Masukkan alamat email Anda seperti yang ditentukan dalam skrip untuk notifikasi error.
- Untuk menggunakan Plivo, Anda harus membeli nomor atau menambahkan nomor ke akun uji coba. Menambahkan nomor Sandbox yang dapat digunakan dengan akun uji coba.
- Tambahkan nomor yang akan muncul sebagai pengirim dan nomor penerima.
- Perbarui
PLIVO_SRC_PHONE_NUMBER
dalam skrip ke salah satu nomor sandbox yang baru saja didaftarkan. Nomor ini harus menyertakan kode negara internasional, misalnya447777123456
untuk nomor Inggris Raya.
Twilio
Twilio adalah layanan lain yang memfasilitasi pengiriman dan penerimaan pesan SMS melalui API-nya. Contoh ini mengilustrasikan pengiriman pesan.
- Daftar ke Twillio.
- Tempelkan contoh skrip ke dalam skrip baru di Google Ads.
- Ganti nilai
TWILIO_ACCOUNT_SID
danTWILIO_ACCOUNT_AUTHTOKEN
dengan nilai yang ditampilkan di halaman konsol akun. - Ganti
TWILIO_SRC_PHONE_NUMBER
dengan nomor dari dasbor--ini adalah nomor yang diizinkan oleh Twilio untuk mengirim pesan.
OAuth 1.0
Banyak layanan populer menggunakan OAuth untuk autentikasi. OAuth hadir dalam berbagai ragam dan versi.
Sementara dengan autentikasi dasar HTTP, pengguna hanya memiliki satu nama pengguna dan sandi, OAuth mengizinkan aplikasi pihak ketiga diberi akses ke akun dan data pengguna menggunakan kredensial khusus untuk aplikasi pihak ketiga tersebut. Selain itu, tingkat akses juga akan spesifik untuk aplikasi tersebut.
Untuk latar belakang tentang OAuth 1.0, lihat panduan Inti OAuth. Secara khusus, lihat 6. Mengautentikasi dengan OAuth. Dalam OAuth 1.0 three-legged penuh, prosesnya adalah sebagai berikut:
- Aplikasi ("Konsumen") mendapatkan token permintaan.
- Pengguna mengizinkan token permintaan.
- Aplikasi menukar token permintaan dengan token akses.
- Untuk semua permintaan resource berikutnya, token akses digunakan dalam permintaan yang ditandatangani.
Agar layanan pihak ketiga dapat menggunakan OAuth 1.0 tanpa interaksi pengguna (misalnya, seperti yang diperlukan skrip Google Ads), langkah 1,2, dan 3 tidak mungkin dilakukan. Oleh karena itu, beberapa layanan mengeluarkan token akses dari konsol konfigurasinya, sehingga aplikasi dapat langsung melanjutkan ke langkah 4. Ini dikenal sebagai {i>one-legged OAuth 1.0<i}.
OAuth 1.0 dalam skrip Google Ads
Untuk skrip Google Ads, setiap skrip biasanya diartikan sebagai aplikasi. Melalui halaman setelan konsol/administrasi untuk layanan, biasanya Anda perlu:
- Siapkan konfigurasi aplikasi, untuk mewakili skrip.
- Tentukan izin yang akan diperluas ke skrip.
- Mendapatkan Kunci konsumen, Rahasia pelanggan, token akses, dan rahasia akses untuk digunakan dengan OAuth bercabang tunggal.
OAuth 2.0
OAuth 2.0 digunakan dalam API populer untuk memberikan akses ke data pengguna. Pemilik akun untuk layanan pihak ketiga tertentu memberikan izin ke aplikasi tertentu untuk mengizinkannya mengakses data pengguna. Kekurangannya adalah pemilik:
- Tidak perlu membagikan kredensial akun pengguna ke aplikasi.
- Dapat mengontrol aplikasi mana yang memiliki akses ke data secara individual, dan sejauh mana Anda dapat mengakses data tersebut. (Misalnya, akses yang diberikan mungkin bersifat hanya-baca, atau hanya ke sebagian data.)
Untuk menggunakan layanan berkemampuan OAuth 2.0 dalam skrip Google Ads, ada beberapa langkah:
- Di luar skrip Anda
Berikan otorisasi untuk Skrip Google Ads guna mengakses data pengguna Anda melalui API pihak ketiga. Pada umumnya, hal ini akan melibatkan penyiapan aplikasi di konsol layanan pihak ketiga. Permohonan ini mewakili Skrip Google Ads Anda.
Anda menentukan hak akses yang harus diberikan pada aplikasi Skrip Google Ads, dan biasanya akan diberikan client ID. Melalui OAuth 2, Anda dapat mengontrol aplikasi mana yang memiliki akses ke data Anda di layanan pihak ketiga, serta aspek data mana yang dapat dilihat atau diubah oleh aplikasi tersebut.
- Dalam skrip Anda
Izinkan dengan server jarak jauh. Bergantung pada jenis pemberian yang diizinkan server, serangkaian langkah berbeda yang dikenal sebagai flow harus diikuti. Namun, pada akhirnya semua akan menghasilkan token akses yang dikeluarkan, yang akan digunakan untuk sesi tersebut bagi semua permintaan berikutnya.
Membuat permintaan API. Teruskan token akses dengan setiap permintaan.
Alur otorisasi
Setiap jenis hibah dan alur yang sesuai melayani berbagai skenario penggunaan. Misalnya, alur yang berbeda digunakan saat pengguna mengikuti sesi interaktif, berbeda dengan skenario saat aplikasi harus berjalan di latar belakang tanpa kehadiran pengguna.
Penyedia API akan menentukan jenis hibah yang mereka terima, dan hal ini akan memandu cara pengguna melanjutkan dalam mengintegrasikan API.
Penerapan
Untuk semua alur OAuth yang berbeda, tujuannya adalah mendapatkan token akses yang kemudian dapat digunakan selama sisa sesi untuk mengautentikasi permintaan.
Library contoh, menunjukkan cara mengautentikasi untuk setiap jenis alur yang berbeda. Setiap metode ini menampilkan objek yang mendapatkan dan menyimpan token akses, serta memfasilitasi permintaan terautentikasi.
Pola penggunaan umumnya adalah:
// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);
Pemberian kredensial klien
Pemberian kredensial klien adalah salah satu bentuk alur OAuth2 yang lebih sederhana, di mana aplikasi bertukar ID dan rahasia, yang unik untuk aplikasi, sebagai imbalan atas penerbitan token akses berbatas waktu.
// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response
Pembaruan pemberian token
Pemberian token refresh mirip dengan pemberian kredensial klien, karena permintaan sederhana ke server akan menampilkan token akses yang dapat digunakan dalam sesi.
Mendapatkan token refresh
Perbedaan dengan pemberian token refresh adalah meskipun detail yang diperlukan untuk pemberian kredensial klien berasal dari konfigurasi aplikasi (misalnya, di panel kontrol layanan), token refresh diberikan sebagai bagian dari alur yang lebih kompleks, seperti pemberian kode otorisasi, yang akan memerlukan interaksi pengguna:
- Menggunakan OAuth Playground untuk mendapatkan token refresh
OAuth2 playground menyediakan UI yang memungkinkan pengguna melakukan pemberian kode otorisasi untuk mendapatkan token refresh.
Tombol setelan di kanan atas memungkinkan Anda menentukan semua parameter yang akan digunakan dalam alur OAuth, termasuk:
- Endpoint otorisasi: Digunakan sebagai awal alur untuk otorisasi.
- Endpoint token: Digunakan dengan token refresh untuk mendapatkan token akses.
- client ID dan rahasia: Kredensial untuk aplikasi.
- Menggunakan skrip untuk mendapatkan token refresh
Alternatif berbasis skrip untuk menyelesaikan alur tersedia dalam contoh pembuatan token refresh.
Perbarui penggunaan token
Setelah otorisasi awal dilakukan, layanan dapat mengeluarkan token refresh yang kemudian dapat digunakan dengan cara yang sama seperti alur kredensial klien. Dua contoh diberikan di bawah ini:
const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response
Contoh Search Ads 360
Search Ads 360 adalah contoh API yang dapat digunakan dengan token refresh. Dalam contoh ini, skrip membuat dan menampilkan laporan. Lihat referensi Search Ads 360 API untuk mengetahui detail selengkapnya tentang tindakan lain yang dapat dilakukan.
Membuat skrip
- Buat project baru di Konsol API, dan dapatkan client ID, rahasia klien, dan token refresh dengan mengikuti prosedur dalam panduan DoubleClick, dan memastikan Anda mengaktifkan DoubleClick Search API.
- Tempel contoh skrip ke dalam skrip baru di Google Ads.
- Tempelkan contoh library OAuth2 di bawah listingan kode.
- Ubah skrip agar berisi nilai yang benar untuk client ID, rahasia klien, dan token refresh.
Contoh Apps Script Execution API
Contoh ini menggambarkan eksekusi fungsi di Apps Script menggunakan Apps Script Execution API. Dengan demikian, Apps Script dapat dipanggil dari skrip Google Ads.
Membuat skrip Apps Script
Buat skrip baru. Contoh berikut akan mencantumkan 10 file dari Drive:
function listFiles() {
const limit = 10;
const files = [];
const fileIterator = DriveApp.getFiles();
while (fileIterator.hasNext() && limit) {
files.push(fileIterator.next().getName());
limit--;
}
return files;
}
Mengonfigurasi Apps Script untuk dijalankan
- Simpan skrip.
- Klik Resource > Project Cloud Platform.
- Klik nama project untuk membuka Konsol API.
- Buka APIs & Services.
- Aktifkan API yang sesuai, dalam hal ini Drive API, dan Apps Script Execution API.
- Buat kredensial OAuth dari item Credentials di menu.
- Kembali ke skrip, publikasikan skrip untuk dieksekusi dari Publish > Deploy as API Executable.
Membuat skrip Google Ads
- Tempel contoh skrip ke dalam skrip baru di Google Ads.
- Selain itu, tempel contoh library OAuth2 di bawah listingan kode.
- Ubah skrip agar berisi nilai yang benar untuk client ID, rahasia klien, dan token refresh.
Akun layanan
Alternatif untuk jenis pemberian di atas adalah konsep akun layanan.
Akun layanan berbeda dari yang di atas karena tidak digunakan untuk mengakses data pengguna: Setelah autentikasi, permintaan dibuat oleh Akun Layanan atas nama aplikasi, bukan sebagai pengguna yang mungkin memiliki project. Misalnya, jika akun layanan menggunakan Drive API untuk membuat file, hal ini akan menjadi milik akun layanan, dan secara default tidak dapat diakses oleh pemilik project.
Contoh Google natural language API
natural language API menyediakan analisis sentimen dan analisis entity untuk teks.
Contoh ini menggambarkan penghitungan sentimen untuk teks iklan—termasuk judul atau deskripsi. Hal ini memberikan ukuran untuk seberapa positif pesan tersebut dan besarnya pesan: Mana yang lebih baik, Kami menjual kue atau Kami menjual kue terbaik di London. Beli sekarang juga!?
Menyiapkan skrip
- Membuat project baru di Konsol API
- Aktifkan Natural Language API
- Aktifkan penagihan untuk project.
- Buat Akun Layanan. Download file JSON kredensial.
- Tempelkan contoh skrip ke skrip baru di Google Ads.
- Selain itu, tempel contoh library OAuth2 di bawah listingan kode.
- Ganti nilai yang diperlukan:
serviceAccount
: Alamat email Akun Layanan, misalnyaxxxxx@yyyy.iam.gserviceaccount.com
.key
: Kunci dari file JSON yang didownload saat membuat Akun Layanan. Dimulai pada-----BEGIN PRIVATE KEY...
dan berakhir pada...END PRIVATE KEY-----\n
.
Respons API
API dapat menampilkan data dalam berbagai format. Yang paling terkenal adalah XML dan JSON.
JSON
JSON biasanya lebih sederhana daripada XML untuk digunakan sebagai format respons. Namun, masih ada beberapa masalah yang bisa muncul.
Validasi jawaban
Setelah mendapatkan respons yang berhasil dari panggilan ke API, langkah umum
berikutnya adalah menggunakan JSON.parse
untuk mengonversi string JSON menjadi objek
JavaScript. Pada tahap ini, sebaiknya tangani kasus ketika penguraian
gagal:
const json = response.getContentText();
try {
const data = JSON.parse(json);
return data;
} catch(e) {
// Parsing of JSON failed - handle error.
}
Selain itu, jika API tidak berada di bawah kendali Anda, pertimbangkan bahwa struktur respons dapat berubah, dan properti mungkin tidak ada lagi:
// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;
// Better approach
if (data && data.queryResponse) {
const answer = data.queryResponse;
} else {
// Format of API response has changed - alert developer or handle accordingly
}
XML
Validasi
XML masih merupakan format yang populer untuk membangun API. Respons dari panggilan API dapat diurai menggunakan metode XmlService
parse
:
const responseText = response.getContentText();
try {
const document = XmlService.parse(responseText);
} catch(e) {
// Error in XML representation - handle accordingly.
}
Meskipun XmlService.parse
mendeteksi error dalam XML dan menampilkan pengecualian
yang sesuai, XmlService.parse
tidak memberikan kemampuan untuk memvalidasi XML terhadap
skema.
Elemen root
Dengan penguraian dokumen XML yang berhasil, elemen root diperoleh
menggunakan metode getRootElement()
:
const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();
Namespace
Dalam contoh berikut, Sportradar API digunakan untuk mendapatkan hasil sepak bola untuk pertandingan yang dipilih. Respons XML mengambil format berikut:
<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
<matches>
...
</matches>
</schedule>
Perhatikan cara namespace ditetapkan dalam elemen root. Oleh karena itu, Anda harus:
- Ekstrak atribut namespace dari dokumen.
- Gunakan namespace ini saat menjelajahi dan mengakses elemen turunan.
Contoh berikut menunjukkan cara mengakses elemen <matches>
dalam cuplikan
dokumen di atas:
const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);
Mendapatkan nilai
Berdasarkan sampel jadwal sepak bola:
<match status="..." category="..." ... >
...
</match>
Atribut dapat diambil, misalnya:
const status = matchElement.getAttribute('status').getValue();
Teks yang terdapat dalam elemen dapat dibaca menggunakan getText()
, tetapi teks ini akan
digabungkan jika ada beberapa turunan teks dari sebuah elemen. Pertimbangkan
untuk menggunakan getChildren()
dan melakukan iterasi pada setiap turunan jika kemungkinan beberapa
turunan teks mungkin terjadi.
Contoh Sportradar
Contoh Sportradar lengkap ini menggambarkan pengambilan detail pertandingan sepak bola, khususnya pertandingan Liga Premier Inggris. football API adalah salah satu dari berbagai feed olahraga yang ditawarkan oleh Sportradar.
Menyiapkan akun Sportradar
- Buka situs developer Sportradar
- Daftar untuk mendapatkan akun uji coba.
- Setelah mendaftar, login ke akun Anda.
- Setelah login, buka MyAccount.
Sportradar memisahkan olahraga yang berbeda ke dalam API yang berbeda. Misalnya, Anda dapat membeli akses ke football API, tetapi tidak ke Tennis API. Setiap Aplikasi yang Anda buat dapat memiliki berbagai olahraga yang terkait dengannya, dan kunci yang berbeda.
- Di bagian Aplikasi, klik Buat Aplikasi baru. Beri nama dan deskripsi aplikasi, lalu abaikan kolom situs.
- Hanya pilih Issue a new key for football Trial Europe v2.
- Klik Daftarkan Pendaftaran.
Setelah berhasil, halaman yang berisi kunci API baru Anda akan muncul.
- Tempelkan contoh skrip ke dalam skrip baru di Google Ads.
- Ganti kunci API di listingan dengan kunci yang diperoleh di atas, lalu edit kolom alamat email.
Pemecahan masalah
Dalam hal bekerja dengan API pihak ketiga, error dapat terjadi karena sejumlah alasan, misalnya:
- Klien mengeluarkan permintaan ke server dalam format yang tidak diharapkan oleh API.
- Klien mengharapkan format respons yang berbeda dari yang ditemui.
- Klien yang menggunakan token atau kunci yang tidak valid, atau nilai yang tersisa sebagai placeholder.
- Klien mencapai batas penggunaan.
- Klien yang memberikan parameter yang tidak valid.
Dalam semua kasus ini, dan lainnya, langkah pertama yang baik dalam mengidentifikasi penyebab masalah adalah memeriksa detail respons yang menyebabkan error.
Uraikan tanggapan
Secara default, respons apa pun yang menampilkan error (kode status 400 atau lebih) akan ditampilkan oleh mesin skrip Google Ads.
Untuk mencegah perilaku ini, serta agar pesan error dan pesan error dapat diperiksa, tetapkan properti muteHttpExceptions
parameter opsional ke UrlFetchApp.fetch
. Contoh:
const params = {
muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
// ... inspect error details...
}
Kode status umum
200 OK
menunjukkan keberhasilan. Jika respons tidak berisi data yang diharapkan, pertimbangkan bahwa:- Beberapa API memungkinkan spesifikasi kolom dan/atau format respons yang akan digunakan. Periksa dokumentasi API untuk mengetahui detailnya.
- Sebuah API dapat memiliki beberapa resource yang bisa dipanggil. Baca dokumentasi untuk menentukan apakah resource lain mungkin lebih sesuai untuk digunakan, dan akan menampilkan data yang Anda butuhkan.
- API mungkin telah berubah sejak kode ditulis. Baca dokumentasi atau developer untuk mendapatkan klarifikasi.
400 Bad Request
biasanya berarti ada sesuatu yang salah dalam pemformatan atau struktur permintaan yang dikirim ke server. Periksa permintaan dan bandingkan dengan spesifikasi API untuk memastikannya sesuai dengan ekspektasi. Lihat Memeriksa permintaan untuk mengetahui detail tentang cara memeriksa permintaan.401 Unauthorized
biasanya berarti API dipanggil tanpa memberikan atau berhasil melakukan otorisasi.- Jika API menggunakan otorisasi dasar, pastikan header
Authorization
dibuat dan disediakan dalam permintaan. - Jika API menggunakan OAuth 2.0, pastikan token akses telah diperoleh dan dimasukkan sebagai token Pembawa.
- Untuk variasi otorisasi lainnya, pastikan kredensial yang diperlukan untuk permintaan diberikan.
- Jika API menggunakan otorisasi dasar, pastikan header
403 Forbidden
menunjukkan bahwa pengguna tidak memiliki izin untuk resource yang diminta.- Pastikan pengguna telah diberi izin yang diperlukan, misalnya, memberi pengguna akses ke file dalam permintaan berbasis file.
404 Not Found
berarti resource yang diminta tidak ada.- Pastikan URL yang digunakan untuk endpoint API sudah benar.
- Jika mengambil resource, periksa apakah resource yang dirujuk ada (misalnya, jika file ada untuk API berbasis file).
Memeriksa permintaan
Permintaan pemeriksaan berguna saat respons API menunjukkan bahwa format permintaan salah, misalnya, kode status 400. Untuk membantu memeriksa permintaan, UrlFetchApp
memiliki metode pendamping untuk metode fetch()
, yang disebut
getRequest()
Alih-alih mengirim permintaan ke server, metode ini membuat permintaan yang akan dikirim, lalu menampilkannya. Hal ini memungkinkan pengguna memeriksa elemen permintaan untuk memastikan permintaan terlihat benar.
Misalnya, jika data formulir dalam permintaan Anda terdiri dari banyak string yang digabungkan bersama, error mungkin terletak pada fungsi yang Anda buat untuk menghasilkan data formulir tersebut. Yang paling sederhana:
const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...
akan memungkinkan Anda untuk memeriksa elemen permintaan.
Catat permintaan dan respons
Untuk membantu seluruh proses pemeriksaan permintaan dan respons terhadap API pihak ketiga, fungsi bantuan berikut dapat digunakan sebagai pengganti langsung untuk UrlFetchApp.fetch()
, untuk mencatat permintaan dan respons.
Ganti semua instance
UrlFetchApp.fetch()
dalam kode Anda denganlogUrlFetch()
.Tambahkan fungsi berikut ke akhir skrip Anda.
function logUrlFetch(url, opt_params) { const params = opt_params || {}; params.muteHttpExceptions = true; const request = UrlFetchApp.getRequest(url, params); console.log('Request: >>> ' + JSON.stringify(request)); const response = UrlFetchApp.fetch(url, params); console.log('Response Code: <<< ' + response.getResponseCode()); console.log('Response text: <<< ' + response.getContentText()); if (response.getResponseCode() >= 400) { throw Error('Error in response: ' + response); } return response; }
Saat menjalankan skrip, detail semua permintaan dan respons akan dicatat dalam log ke konsol, sehingga proses debug lebih mudah.