API Pihak Ketiga

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: Kami membahas beberapa skenario autentikasi umum.
  • Mengurai respons: Cara memproses data JSON dan XML yang ditampilkan.

Kami juga menyertakan contoh untuk sejumlah API populer yang mengilustrasikan konsep ini.

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-nya 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 memberikan contoh otorisasi pertama kami: Parameter apikey diperlukan, dan nilainya unik untuk setiap pengguna. Kunci ini diperoleh melalui pendaftaran.

Setelah mendaftar, permintaan yang menggunakan kunci dapat dikeluarkan 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());

Menjalankan kode ini akan menghasilkan string panjang teks JSON yang ditulis ke jendela logging di skrip Google Ads.

Langkah berikutnya adalah mengonversi ini ke format yang dapat digunakan dalam skrip Anda.

Data JSON

Banyak API memberikan respons dalam format JSON. Hal ini mewakili serialisasi objek JavaScript, sehingga objek, array, dan jenis dasar dapat direpresentasikan dan ditransfer sebagai string.

Untuk mengonversi string JSON—seperti yang ditampilkan dari OpenWeatherMap—kembali menjadi objek JavaScript, gunakan metode JSON.parse bawaan. Melanjutkan contoh sebelumnya:

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.

Lihat bagian Mengurai respons untuk mengetahui detail selengkapnya tentang cara menggunakan respons API dalam berbagai format.

Penanganan error

Penanganan error adalah pertimbangan penting saat menggunakan API pihak ketiga dalam skrip Anda karena API pihak ketiga sering kali berubah dan menghasilkan nilai respons yang tidak terduga, misalnya:

  • URL atau parameter untuk API dapat berubah tanpa sepengetahuan Anda.
  • Kunci API Anda (atau kredensial pengguna lainnya) dapat habis masa berlakunya.
  • 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 harus 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, Anda mungkin tidak langsung mengetahui perubahan yang mungkin memengaruhi skrip Anda. Misalnya, jika properti name yang ditampilkan dalam contoh OpenWeatherMap diubah menjadi locationName, skrip yang menggunakan properti ini akan gagal.

Oleh karena itu, sebaiknya uji apakah struktur yang ditampilkan sesuai dengan 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 mengirim pesan SMS, akan memerlukan metode lain, seperti POST atau PUT.

Untuk mengilustrasikan penggunaan panggilan POST dengan UrlFetchApp, contoh berikut menunjukkan integrasi dengan Slack, aplikasi pesan kolaboratif, untuk mengirim pesan Slack ke pengguna dan grup Slack.

Siapkan Slack

Panduan ini mengasumsikan bahwa Anda telah mendaftar untuk akun Slack.

Seperti OpenWeatherMap dalam 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 Integrasi Webhook Masuk dengan mengklik Add Incoming WebHooks Integration dan mengikuti petunjuknya. Proses ini akan mengeluarkan URL yang akan digunakan untuk pengiriman pesan.

Membuat permintaan POST

Setelah menyiapkan Webhook Masuk, membuat permintaan POST memerlukan penggunaan beberapa properti tambahan dalam parameter options yang diteruskan ke UrlFetchApp.fetch:

  • method: Seperti yang disebutkan, setelan ini ditetapkan secara default ke GET, tetapi di sini kita menggantinya dan menyetelnya ke POST.
  • payload: Ini adalah data yang akan dikirim ke server sebagai bagian dari permintaan POST. Dalam contoh ini, Slack mengharapkan objek yang diserialisasi ke format JSON seperti yang dijelaskan dalam dokumentasi Slack. Untuk ini, metode [JSON.stringify][json-stringify-url] digunakan, dan Content-Type ditetapkan ke application/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 sebelumnya menunjukkan kode minimum yang diperlukan untuk mengaktifkan pesan masuk ke Slack. Contoh yang diperluas mengilustrasikan pembuatan dan pengiriman Laporan Performa Kampanye ke grup, serta beberapa opsi pemformatan dan tampilan.

Pesan masuk

Lihat pemformatan pesan dalam dokumentasi Slack untuk mengetahui detail selengkapnya tentang pesan Slack.

Data formulir

Contoh sebelumnya 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 form-data:

    subject=Test&to=mail@example.com&body=Hello,+World!
    

    Selain itu, header Content-Type untuk permintaan ditetapkan ke application/x-www-form-urlencoded.

Beberapa API memerlukan penggunaan data formulir saat mengirimkan permintaan POST, jadi 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 di setiap permintaan.

Autentikasi dasar HTTP

Membuat permintaan

Langkah-langkah berikut diperlukan untuk menghasilkan permintaan yang diautentikasi:

  1. Buat frasa sandi dengan menggabungkan nama pengguna dan sandi dengan titik dua, misalnya username:password.
  2. Lakukan encoding base64 pada frasa sandi, misalnya username:password menjadi dXNlcm5hbWU6cGFzc3dvcmQ=.
  3. Lampirkan header Authorization ke permintaan, dalam bentuk Authorization: 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);

Contoh autentikasi dasar

Bagian contoh kode berisi dua contoh yang menggambarkan penggunaan Autentikasi Dasar HTTP:

Plivo

Plivo adalah layanan yang memfasilitasi pengiriman dan penerimaan pesan SMS dengan API-nya. Contoh ini mengilustrasikan pengiriman pesan.

  1. Daftar ke Plivo.
  2. Tempelkan contoh skrip ke dalam skrip baru di Google Ads.
  3. Ganti nilai PLIVO_ACCOUNT_AUTHID dan PLIVO_ACCOUNT_AUTHTOKEN dengan nilai dari dasbor pengelolaan.
  4. Masukkan alamat email Anda seperti yang ditentukan dalam skrip untuk notifikasi error.
  5. Untuk menggunakan Plivo, Anda harus membeli nomor atau menambahkan nomor ke akun uji coba. Tambahkan nomor Sandbox yang dapat digunakan dengan akun uji coba.
  6. Tambahkan nomor yang akan muncul sebagai pengirim, dan nomor penerima.
  7. Perbarui PLIVO_SRC_PHONE_NUMBER dalam skrip ke salah satu nomor sandbox yang baru saja didaftarkan. Nomor ini harus menyertakan kode negara internasional, misalnya 447777123456 untuk nomor Inggris Raya.

Twilio

Twilio adalah layanan lain yang memfasilitasi pengiriman dan penerimaan pesan SMS dengan API-nya. Contoh ini mengilustrasikan pengiriman pesan.

  1. Daftar ke Twillio.
  2. Tempelkan contoh skrip ke dalam skrip baru di Google Ads.
  3. Ganti nilai TWILIO_ACCOUNT_SID dan TWILIO_ACCOUNT_AUTHTOKEN dengan nilai yang ditampilkan di halaman konsol akun.
  4. 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 sejumlah ragam dan versi.

Meskipun dengan autentikasi dasar HTTP, pengguna hanya memiliki satu nama pengguna dan sandi, OAuth memungkinkan aplikasi pihak ketiga diberi akses ke akun dan data pengguna, menggunakan kredensial khusus untuk aplikasi pihak ketiga tersebut. Selain itu, cakupan akses juga akan khusus untuk aplikasi tersebut.

Untuk mengetahui latar belakang OAuth 1.0, lihat panduan OAuth Core. Secara khusus, lihat 6. Mengautentikasi dengan OAuth. Dalam OAuth 1.0 three-legged penuh, prosesnya adalah sebagai berikut:

  1. Aplikasi ("Konsumen") mendapatkan token permintaan.
  2. Pengguna memberikan otorisasi pada token permintaan.
  3. Aplikasi menukar token permintaan dengan token akses.
  4. Untuk semua permintaan resource berikutnya, token akses digunakan dalam permintaan bertanda tangan.

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 dapat dilakukan. Oleh karena itu, beberapa layanan mengeluarkan token akses dari konsol konfigurasinya, sehingga aplikasi dapat langsung melanjutkan ke langkah 4. Hal ini dikenal sebagai OAuth 1.0 satu kaki.

OAuth1

OAuth 1.0 di skrip Google Ads

Untuk skrip Google Ads, setiap skrip biasanya ditafsirkan sebagai aplikasi. Melalui halaman setelan konsol atau administrasi untuk layanan, biasanya perlu:

  • Siapkan konfigurasi aplikasi, untuk mewakili skrip.
  • Tentukan izin yang diperluas ke skrip.
  • Dapatkan Consumer key, Consumer secret, token akses, dan rahasia akses untuk digunakan dengan OAuth satu kaki.

OAuth 2.0

OAuth 2.0 digunakan di API populer untuk memberikan akses ke data pengguna. Pemilik akun untuk layanan pihak ketiga tertentu memberikan izin kepada aplikasi tertentu untuk mengizinkan aplikasi tersebut mengakses data pengguna. Keuntungannya adalah pemilik:

  • Tidak perlu membagikan kredensial akunnya kepada aplikasi.
  • Dapat mengontrol aplikasi mana yang memiliki akses ke data satu per satu, dan sejauh mana. (Misalnya, akses yang diberikan mungkin hanya baca, atau hanya ke subset data.)

Untuk menggunakan layanan yang mendukung OAuth 2.0 di skrip Google Ads, ada beberapa langkah:

Di luar skrip Anda

Berikan otorisasi untuk skrip Google Ads agar dapat mengakses data pengguna Anda melalui API pihak ketiga. Dalam sebagian besar kasus, hal ini akan melibatkan penyiapan aplikasi di konsol layanan pihak ketiga. Aplikasi ini mewakili skrip Anda.

Anda menentukan hak akses yang harus diberikan kepada aplikasi skrip Google Ads, dan biasanya aplikasi tersebut akan diberi client ID. Hal ini memungkinkan Anda, melalui OAuth 2.0, mengontrol aplikasi mana yang memiliki akses ke data Anda di layanan pihak ketiga, dan juga, aspek data mana yang dapat dilihat atau diubah oleh aplikasi tersebut.

Dalam skrip Anda

Lakukan otorisasi dengan server jarak jauh. Bergantung pada jenis pemberian yang diizinkan server, serangkaian langkah yang berbeda, yang dikenal sebagai alur, harus diikuti, tetapi semuanya pada akhirnya akan menghasilkan token akses yang akan digunakan untuk sesi tersebut untuk semua permintaan berikutnya.

Membuat permintaan API. Teruskan token akses dengan setiap permintaan.

Alur otorisasi

Setiap jenis pemberian izin dan alur yang sesuai melayani skenario penggunaan yang berbeda. Misalnya, alur yang berbeda digunakan saat pengguna berpartisipasi dalam sesi interaktif, berbeda dengan skenario saat aplikasi harus berjalan di latar belakang tanpa kehadiran pengguna.

Penyedia API akan memutuskan jenis pemberian yang mereka terima, dan ini akan memandu cara pengguna melanjutkan integrasi API mereka.

Penerapan

Untuk semua alur OAuth yang berbeda, tujuannya adalah untuk mendapatkan token akses yang kemudian dapat digunakan selama sisa sesi untuk mengautentikasi permintaan.

Library contoh, mengilustrasikan cara melakukan autentikasi untuk setiap jenis alur yang berbeda. Setiap metode ini menampilkan objek yang mendapatkan dan menyimpan token akses, serta memfasilitasi permintaan yang diautentikasi.

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][client-credentials-rfc] adalah salah satu bentuk alur OAuth2 yang lebih sederhana, di mana aplikasi menukar ID dan rahasia, yang unik untuk aplikasi, sebagai imbalan atas penerbitan token akses yang dibatasi waktu.

Kredensial klien

// 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

Pemberian token refresh

Pemberian token refresh mirip dengan pemberian kredensial klien, yaitu permintaan ke server akan menampilkan token akses yang dapat digunakan dalam sesi.

Token refresh

Mendapatkan token refresh

Perbedaannya 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][authorization-code-rfc], yang akan memerlukan interaksi pengguna:

Kode otorisasi

Menggunakan OAuth Playground untuk mendapatkan token refresh

OAuth2 playground menyediakan UI yang memungkinkan pengguna melakukan langkah-langkah 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.
  • Token endpoint: Digunakan dengan token refresh untuk mendapatkan token akses.
  • client ID dan secret: Kredensial untuk aplikasi.

    OAuth Playground

Penggunaan token refresh

Setelah otorisasi awal dilakukan, layanan dapat menerbitkan token refresh yang kemudian dapat digunakan dengan cara yang mirip dengan alur kredensial klien:

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 API Search Ads 360 untuk mengetahui detail lengkap tindakan lain yang dapat dilakukan.

Membuat skrip
  1. Buat project baru di Konsol Google Cloud, dan dapatkan client ID, rahasia klien, dan token refresh dengan mengikuti prosedur dalam panduan Search Ads 360, serta memastikan bahwa Anda mengaktifkan Search Ads 360 API.
  2. Tempel [contoh skrip][search-ads-360-example] ke skrip baru di Google Ads.
  3. Tempelkan [contoh library OAuth2][oauth20-library-example] di bawah listingan kode.
  4. Ubah skrip agar berisi nilai yang benar untuk client ID, rahasia klien, dan token refresh.

Contoh Apps Script Execution API

Contoh ini mengilustrasikan cara menjalankan fungsi di Apps Script menggunakan Apps Script Execution API. Dengan begitu, Anda dapat memanggil Apps Script 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 eksekusi
  1. Simpan skrip.
  2. Klik Resources > Cloud Platform project.
  3. Klik nama project untuk membuka Konsol Google Cloud.
  4. Buka APIs & Services.
  5. Aktifkan API yang sesuai, dalam hal ini Drive API, dan Apps Script Execution API.
  6. Buat kredensial OAuth dari item Credentials di menu.
  7. Kembali ke skrip Anda, publikasikan skrip untuk dieksekusi dari Publish > Deploy as API Executable.
Membuat skrip Google Ads
  1. Tempelkan contoh skrip ke skrip baru di Google Ads.
  2. Selain itu, tempelkan [contoh library OAuth2][oauth20-library-example] di bawah listingan kode.
  3. Ubah skrip agar berisi nilai yang benar untuk client ID, rahasia klien, dan token refresh.

Akun layanan

Alternatif untuk jenis pemberian adalah konsep akun layanan.

Akun layanan berbeda dengan jenis pemberian 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, file ini akan menjadi milik akun layanan, dan secara default tidak akan dapat diakses oleh pemilik project.

Contoh Google Natural Language API

[Natural Language API][natural-language-api-docs] menyediakan [analisis sentimen][sentiment-analysis-api-docs] dan [analisis entity][entity-analysis-api-docs] untuk teks.

Contoh ini menggambarkan penghitungan [sentimen][sentiment-api-docs] untuk teks iklan—termasuk judul atau deskripsi. Hal ini memberikan ukuran 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
  1. Buat project baru di Konsol Google Cloud.
  2. Aktifkan [Natural Language API][natural-language-api].
  3. Aktifkan penagihan untuk project.
  4. [Membuat Akun Layanan][create-service-account]. Download file JSON kredensial.
  5. Tempelkan [contoh skrip][natural-language-example] ke skrip baru di Google Ads.
  6. Selain itu, tempelkan [contoh library OAuth2][oauth20-library-example] di bawah listingan kode.
  7. Ganti nilai yang diperlukan:
    • serviceAccount: Alamat email Akun Layanan, misalnya xxxxx@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 di antaranya adalah XML dan JSON.

JSON

JSON biasanya lebih mudah digunakan daripada XML sebagai format respons. Namun, masih ada beberapa masalah yang dapat muncul.

Validasi respons

Setelah mendapatkan respons yang berhasil dari panggilan ke API, langkah berikutnya yang umum dilakukan adalah menggunakan JSON.parse untuk mengonversi string JSON menjadi objek JavaScript. Pada tahap ini, sebaiknya tangani kasus saat 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

XmlService memungkinkan skrip Anda mengurai dan mengekstrak data dari isi respons XML.

Validasi

XML masih menjadi format populer untuk membangun API. Respons dari panggilan API dapat diurai menggunakan metode parse XmlService:

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, library ini tidak menyediakan kemampuan untuk memvalidasi XML terhadap skema.

Elemen root

Jika penguraian dokumen XML berhasil, elemen root akan diperoleh menggunakan metode getRootElement():

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

Namespace

Dalam contoh berikut, Sportradar API digunakan untuk mendapatkan hasil pertandingan sepak bola untuk pertandingan yang dipilih. Respons XML menggunakan format berikut:

<schedule_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

Perhatikan bagaimana namespace ditentukan dalam elemen root. Oleh karena itu, Anda perlu:

  • Ekstrak atribut namespace dari dokumen.
  • Gunakan namespace ini saat melintasi dan mengakses elemen turunan.

Contoh berikut menunjukkan cara mengakses elemen <schedule> dan menelusuri elemen turunan <sport_event>-nya dalam cuplikan dokumen sebelumnya:

const document = XmlService.parse(xmlText);
const rootElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = rootElement.getNamespace();
const scheduleElement = rootElement.getChild('schedule', namespace);
const sportEvents = scheduleElement.getChildren('sport_event', namespace);

Mendapatkan nilai

Dengan contoh dari jadwal pertandingan sepak bola:

<sport_event_status status="..." ... />

Atribut dapat diambil, misalnya:

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.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 dalam kasus yang mungkin memiliki beberapa turunan teks.

Contoh Sportradar

Contoh Sportradar lengkap ini mengilustrasikan pengambilan detail pertandingan sepak bola, khususnya pertandingan Liga Premier Inggris. Soccer API adalah salah satu dari berbagai feed olahraga yang ditawarkan oleh Sportradar.

Menyiapkan akun Sportradar
  1. Buka situs developer Sportradar
  2. Daftar untuk mendapatkan akun uji coba.
  3. Setelah mendaftar, login ke akun Anda.
  4. Setelah login, buka Akun Saya.

Sportradar memisahkan berbagai olahraga ke dalam API yang berbeda. Misalnya, Anda dapat membeli akses ke Soccer API, tetapi tidak ke Tennis API. Setiap Aplikasi yang Anda buat dapat memiliki olahraga yang berbeda, dan kunci yang berbeda.

  1. Di bagian Applications, klik Create a new Application. Beri nama dan deskripsi pada aplikasi, dan abaikan kolom situs.
  2. Pilih hanya Issue a new key for Soccer Trial Europe v2.
  3. Klik Register Application.

Jika berhasil, tindakan ini akan menghasilkan halaman yang berisi kunci API baru Anda.

  1. Tempelkan contoh skrip ke skrip baru di Google Ads.
  2. Ganti kunci API dalam listingan dengan kunci yang baru diterbitkan, dan edit kolom alamat email.

Pemecahan masalah

Saat menggunakan API pihak ketiga, error dapat terjadi karena sejumlah alasan, misalnya:

  • Klien yang mengirimkan permintaan ke server dalam format yang tidak diharapkan oleh API.
  • Klien mengharapkan format respons yang berbeda dari yang ditemukan.
  • Klien yang menggunakan token atau kunci yang tidak valid, atau nilai yang dibiarkan sebagai placeholder.
  • Klien mencapai batas penggunaan.
  • Klien memberikan parameter yang tidak valid.

Dalam semua kasus ini, dan kasus lainnya, langkah pertama yang baik untuk mengidentifikasi penyebab masalah adalah dengan memeriksa detail respons yang menyebabkan error.

Mengurai respons

Secara default, setiap respons yang menampilkan error (kode status 400 atau lebih) akan ditampilkan oleh mesin skrip Google Ads.

Untuk mencegah perilaku ini, dan agar error dan pesan error dapat diperiksa, tetapkan properti muteHttpExceptions dari 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 penentuan kolom, format respons, atau keduanya, yang akan digunakan. Periksa dokumentasi API untuk mengetahui detailnya.
    • API mungkin memiliki beberapa resource yang dapat dipanggil. Lihat dokumentasi untuk menentukan apakah resource lain mungkin lebih sesuai untuk digunakan, dan akan menampilkan data yang Anda perlukan.
    • API mungkin telah berubah sejak kode ditulis. Lihat dokumentasi atau hubungi 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 memastikan permintaan tersebut sesuai dengan harapan. 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 sedang dibuat dan disediakan dalam permintaan.
    • Jika API menggunakan OAuth 2.0, pastikan token akses telah diperoleh dan disediakan sebagai token Bearer.
    • Untuk variasi otorisasi lainnya, pastikan kredensial yang diperlukan untuk permintaan disediakan.
  • 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, pastikan resource yang direferensikan ada (misalnya, jika file ada untuk API berbasis file).

Memeriksa permintaan

Memeriksa permintaan berguna saat respons API menunjukkan bahwa permintaan tidak terbentuk dengan baik, misalnya, kode status 400. Untuk membantu memeriksa permintaan, UrlFetchApp memiliki metode pendamping untuk metode fetch(), yang disebut getRequest(url, params)

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, error mungkin terletak pada fungsi yang Anda buat untuk menghasilkan data formulir tersebut. Secara sederhana:

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

akan memungkinkan Anda memeriksa elemen permintaan.

Mencatat permintaan dan respons ke dalam log

Untuk membantu seluruh proses pemeriksaan permintaan dan respons ke API pihak ketiga, fungsi bantuan berikut dapat digunakan sebagai pengganti langsung untuk UrlFetchApp.fetch(), guna mencatat permintaan dan respons.

  1. Ganti semua instance UrlFetchApp.fetch() dalam kode Anda dengan logUrlFetch().

  2. 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 ke konsol, sehingga proses debug menjadi lebih mudah.

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities