API Pihak Ketiga

Fitur canggih skrip Google Ads adalah kemampuan untuk berintegrasi dengan data dan layanan dari API pihak ketiga.

Panduan ini mencakup konsep-konsep berikut yang dapat membantu Anda menulis skrip hubungkan 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.

Kami juga menyertakan sampel untuk nomor tertentu beberapa API populer yang menggambarkan konsep ini.

Catatan: Secara tertulis atau dengan skrip yang memanfaatkan API pihak ketiga, sebaiknya meninjau Persyaratan dan Ketentuan yang terkait dengan API untuk memastikan penggunaan yang Anda maksudkan mematuhinya.

Mengambil data dengan UrlFetchApp

UrlFetchApp menyediakan fungsi inti yang diperlukan untuk berinteraksi dengan API pihak ketiga.

Catatan: UrlFetchApp adalah dasar untuk berinteraksi dengan API pihak ketiga, tetapi, ada kuota pada penggunaannya, yang harus Anda ketahui ketika mengembangkan solusi.

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 kita: Parameter apikey adalah diperlukan, dan nilainya unik untuk setiap pengguna. Kunci ini diperoleh melalui mendaftar.

Setelah pendaftaran, 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());

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

Langkah selanjutnya adalah mengonversi ini ke format yang dapat digunakan dalam {i>script<i}.

Data JSON

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

Untuk mengonversi string JSON—seperti yang ditampilkan dari OpenWeatherMap—kembali ke objek JavaScript, menggunakan Metode JSON.parse. 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.

Lihat bagian Respons Parse untuk detail selengkapnya tentang bekerja dengan respons API dalam berbagai format.

Penanganan error

Penanganan error merupakan pertimbangan penting saat menggunakan API pihak ketiga dalam skrip Anda karena API pihak ketiga sering berubah dan membuat 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 habis masa berlakunya.
• Format respons dapat berubah tanpa pemberitahuan.

Kode status HTTP

Karena adanya potensi respons yang tidak terduga, Anda harus memeriksa objek HTTP kode status Anda. Secara {i>default<i}, UrlFetchApp akan menampilkan pengecualian jika ditemukan kode error HTTP. Kepada 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 mempengaruhi skrip mereka. Misalnya, jika properti name yang ditampilkan dalam contoh OpenWeatherMap diubah menjadi locationName, skrip menggunakan properti ini akan gagal.

Oleh karena itu, sebaiknya uji 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 dapat mengambil data. Biasanya, panggilan API yang tidak mengubah status pada remote server menggunakan 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, fitur pesan kolaboratif untuk mengirim pesan Slack kepada pengguna dan grup Slack.

Siapkan Slack

Panduan ini mengasumsikan bahwa Anda telah mendaftar untuk akun Slack.

Seperti halnya OpenWeatherMap di contoh sebelumnya, Anda perlu memperoleh token untuk mengaktifkan pengiriman pesan. Slack menyediakan URL unik agar Anda dapat mengirim pesan ke tim Anda yang disebut Webhook Masuk.

Siapkan Webhook Masuk dengan mengklik Tambahkan Integrasi WebHook Masuk, lalu ikuti petunjuknya. Tujuan harus mengeluarkan URL untuk digunakan dalam pesan.

Membuat permintaan POST

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

• method: Seperti yang telah disebutkan, default-nya adalah GET, tetapi di sini kita menggantinya dan tetapkan ke POST.

• payload: Ini adalah data yang akan dikirim ke server sebagai bagian dari POST permintaan. Dalam contoh ini, Slack mengharapkan objek yang diserialisasi ke format JSON seperti yang dijelaskan dalam Slack dokumentasi tambahan. Untuk melakukannya, JSON.stringify digunakan, dan Content-Type disetel 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 di atas menunjukkan jumlah minimum untuk mengaktifkan pesan masuk ke Slack. Channel contoh yang diperluas mengilustrasikan pembuatan dan pengiriman kampanye Performa Kampanye Laporkan ke serta beberapa opsi format dan tampilan.

Lihat pemformatan pesan di Slack untuk 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: '[e-mail]', subject:'Test', body:'Hello, World!'}
  

  Key-value pair dikonversi menjadi data formulir:

  subject=Test&to=[e-mail]&body=Hello,+World!
  

  Header Content-Type untuk permintaan juga disetel 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 berguna untuk diterapkan saat ini.

Autentikasi dasar HTTP

HTTP dasar autentikasi adalah salah satu bentuk otentikasi yang paling sederhana dan digunakan oleh banyak API.

Otentikasi dilakukan dengan melampirkan nama pengguna dan {i>password<i} yang dienkode ke header HTTP di setiap permintaan.

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. Enkode frasa sandi Base64, 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

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

• Mengirim pesan SMS melalui Plivo
• Mengirim pesan SMS melalui Twilio

Plivo

Plivo adalah layanan yang memfasilitasi pengiriman dan menerima pesan SMS melalui API mereka. Contoh ini menggambarkan pengiriman membuat pesan teks.

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 dari dasbor pengelolaan.
4. Masukkan alamat email Anda seperti yang ditentukan dalam skrip untuk notifikasi tentang yang sama.
5. Untuk menggunakan Plivo, Anda harus membeli nomor atau menambahkan nomor ke uji coba menggunakan akun layanan. Menambahkan nomor Sandbox yang dapat digunakan dengan akun uji coba.
6. Tambahkan nomor yang akan muncul sebagai pengirim dan penerima angka
7. Perbarui PLIVO_SRC_PHONE_NUMBER di skrip ke salah satu nomor sandbox baru saja terdaftar. Kode ini harus mencakup kode negara internasional, untuk contoh 447777123456 untuk nomor Inggris Raya.

Twilio

Twilio adalah layanan lain yang memfasilitasi pengiriman dan menerima pesan SMS melalui API mereka. Contoh ini menggambarkan pengiriman membuat pesan teks.

1. Daftar ke Twillio.
2. Tempelkan contoh skrip ke skrip baru di Google Ads.
3. Ganti nilai TWILIO_ACCOUNT_SID dan TWILIO_ACCOUNT_AUTHTOKEN dengan yang ditampilkan di halaman konsol akun.
4. Ganti TWILIO_SRC_PHONE_NUMBER dengan nomor dari dasbor--ini adalah nomor yang diotorisasi oleh Twilio untuk mengirim pesan.

OAuth 1.0

Banyak layanan populer menggunakan OAuth untuk proses autentikasi. OAuth hadir dalam beberapa {i>flavor <i}dan versinya.

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

Untuk latar belakang tentang OAuth 1.0, lihat panduan Inti OAuth. Secara khusus, lihat 6. Mengautentikasi dengan OAuth. Berkaki tiga penuh OAuth 1.0, prosesnya adalah sebagai berikut:

1. Aplikasi ("Pelanggan") memperoleh token permintaan.
2. Pengguna memberikan otorisasi token permintaan.
3. Aplikasi menukar token permintaan dengan token akses.
4. Untuk semua permintaan resource berikutnya, token akses digunakan dalam permintaan.

Agar layanan pihak ketiga dapat menggunakan OAuth 1.0 tanpa interaksi pengguna (misalnya sebagaimana diperlukan skrip Google Ads) langkah 1,2, dan 3 tidak dapat dilakukan. Oleh karena itu, beberapa layanan mengeluarkan token akses dari konfigurasi mereka konsol, sehingga aplikasi dapat langsung melanjutkan ke langkah 4. Hal ini dikenal sebagai {i>one-legged OAuth<i} 1.0.

OAuth 1.0 di skrip Google Ads

Untuk skrip Google Ads, setiap skrip biasanya ditafsirkan sebagai aplikasi. Melalui halaman setelan konsol/administrasi untuk layanan tersebut, biasanya diperlukan untuk:

• Menyiapkan konfigurasi aplikasi, untuk mewakili skrip.
• Tentukan izin yang ditambahkan ke skrip.
• Mendapatkan Kunci konsumen, Rahasia konsumen, token akses, dan rahasia akses untuk digunakan dengan OAuth bercabang satu.

OAuth 2.0

OAuth 2.0 digunakan di API populer untuk memberikan akses ke data pengguna. Pemilik akun untuk pemberian layanan pihak ketiga tertentu izin akses ke aplikasi tertentu agar mereka dapat mengakses data pengguna. Tujuan keuntungannya adalah pemilik:

• Tidak perlu membagikan kredensial akun mereka dengan aplikasi.
• Dapat mengontrol aplikasi mana yang memiliki akses ke data secara individual, dan sejauh mana. (Misalnya, akses yang diberikan mungkin hanya-baca, atau hanya untuk {i>subset<i} data.)

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

Di luar skrip Anda

Berikan otorisasi pada Skrip Google Ads untuk mengakses data pengguna Anda melalui API pihak ketiga. Dalam kebanyakan kasus, hal ini akan melibatkan pengaturan application di konsol layanan pihak ketiga. Aplikasi ini mewakili Skrip Google Ads Anda.

Anda menentukan hak akses yang harus diberikan aplikasi Google Ads Script dan biasanya akan diberikan ID klien. Hal ini memungkinkan Anda, melalui OAuth 2 untuk mengontrol aplikasi mana yang memiliki akses ke data Anda di layanan pihak ketiga, dan juga, aspek data mana yang dapat mereka lihat atau modifikasi.

Dalam skrip Anda

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

Membuat permintaan API. Teruskan token akses dengan setiap permintaan.

Alur otorisasi

Setiap jenis pemberian dan alur yang sesuai dapat mengakomodasi skenario penggunaan yang berbeda. Sebagai misalnya, alur yang berbeda digunakan ketika pengguna mengambil bagian dalam berbeda, berbeda dengan skenario di mana aplikasi harus berjalan di latar belakang tanpa kehadiran pengguna.

Penyedia API akan memutuskan jenis hibah mana yang mereka terima, dan hal ini akan memandu cara pengguna melanjutkan mengintegrasikan API mereka.

Penerapan

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

Library contoh, menggambarkan cara mengotentikasi untuk setiap jenis alur yang berbeda. Tiap-tiap menampilkan objek yang memperoleh dan menyimpan token akses, serta memfasilitasi permintaan yang diotentikasi.

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);

Catatan: Karena skrip Google Ads berumur pendek, tidak ada upaya yang dilakukan dalam contoh ini library untuk memperbarui token akses yang diperoleh.

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 permohonan, 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

Muat ulang pemberian token

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

Mendapatkan token refresh

Perbedaannya dengan pemberian token refresh adalah bahwa 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 kode otorisasi hibah, yang akan mengharuskan interaksi:

Menggunakan OAuth Playground untuk mendapatkan token refresh

Playground OAuth2 menyediakan UI yang memungkinkan pengguna untuk menelusuri pemberian kode otorisasi untuk mendapatkan token pembaruan.

Tombol setelan di kanan atas memungkinkan Anda menentukan semua parameter untuk 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 and secret: Kredensial untuk aplikasi.

Menggunakan skrip untuk mendapatkan token refresh

Alternatif berbasis skrip untuk menyelesaikan alur tersedia di token refresh pembuatan konten contoh.

Muat ulang penggunaan token

Setelah otorisasi awal dilakukan, layanan dapat mengeluarkan pembaruan yang kemudian dapat digunakan dengan cara yang mirip dengan 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 mengembalikan laporan. Lihat Iklan Penelusuran Referensi 360 API untuk mengetahui detail selengkapnya tentang tindakan lainnya yang dapat dilakukan.

Membuat skrip

1. Buat project baru di Konsol API, dan mendapatkan client ID, rahasia klien, dan token refresh dengan mengikuti prosedur dalam panduan DoubleClick, untuk memastikan bahwa Anda mengaktifkan API DoubleClick Search.
2. Tempelkan contoh skrip ke dalam skrip skrip baru di Google Ads.
3. Tempel contoh OAuth2 library di bawah listingan kode Anda.
4. Mengubah skrip agar berisi nilai yang benar untuk {i>client ID<i}, rahasia klien, dan token pembaruan.

Contoh Apps Script Execution API

Contoh ini menggambarkan cara mengeksekusi fungsi di Apps Script menggunakan Apps Script Execution API. Ini memungkinkan Apps Script 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 dieksekusi

1. Simpan skrip.
2. Klik Resource > project Cloud Platform.
3. Klik nama project untuk membuka Konsol API.
4. Buka APIs & Layanan.
5. Mengaktifkan API yang sesuai, dalam hal ini Drive API, dan Aplikasi Eksekusi Skrip API baru.
6. Buat kredensial OAuth dari item Credentials di menu.
7. Kembali ke skrip Anda, publikasikan skrip untuk dieksekusi dari Publish > Deploy sebagai API yang Dapat Dieksekusi.

Membuat skrip Google Ads

1. Tempelkan contoh skrip menjadi skrip baru di Google Ads.
2. Selain itu, tempelkan contoh OAuth2 library di bawah listingan kode Anda.
3. Mengubah skrip agar berisi nilai yang benar untuk {i>client ID<i}, rahasia klien, dan token pembaruan.

Akun layanan

Alternatif untuk jenis pemberian di atas adalah konsep layanan akun Google.

Akun layanan berbeda dari yang disebutkan di atas karena tidak digunakan untuk mengakses pengguna data: Setelah autentikasi, permintaan dibuat oleh Akun Layanan atas nama aplikasi, bukan sebagai pengguna yang mungkin memiliki proyek tersebut. Misalnya, jika akun layanan menggunakan Drive API untuk membuat file, termasuk dalam akun layanan, dan secara default tidak dapat diakses pemilik proyek.

Contoh Google natural language API

natural language API menyediakan sentimen analisis dan entitas analisis untuk teks.

Contoh ini menggambarkan penghitungan sentimen untuk teks iklan—termasuk judul atau deskripsi. Tabel ini mengukur untuk seberapa positif pesannya dan besarnya pesannya: Mana yang lebih baik, Kami menjual kue atau Kami menjual kue terbaik di London. Beli sekarang!?

Menyiapkan skrip

1. Membuat project baru di Konsol API
2. Aktifkan Natural Language API
3. Aktifkan penagihan untuk project.
4. Membuat Layanan Akun. Download file JSON kredensial.
5. Tempelkan contoh skrip ke skrip skrip di Google Ads.
6. Selain itu, tempelkan contoh OAuth2 library di bawah listingan kode Anda.
7. Ganti nilai yang diperlukan:
   • serviceAccount: Alamat email Akun Layanan, misalnya [e-mail].
   • key: Kunci dari file JSON yang didownload saat membuat Layanan menggunakan Akun Layanan Anda. 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 dalam format respons. Namun, masih ada beberapa masalah yang bisa muncul.

Validasi respons

Setelah memperoleh respons berhasil dari panggilan ke API, metode langkah berikutnya adalah menggunakan JSON.parse untuk mengonversi string JSON ke JavaScript . Pada tahap ini, adalah wajar untuk menangani kasus di mana penguraian gagal:

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

Juga, 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 XmlService parse berikut:

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

Saat XmlService.parse mendeteksi error dalam XML dan menampilkan pengecualian karenanya, DNS tidak memberikan kemampuan untuk memvalidasi XML terhadap skema.

Elemen root

Jika penguraian dokumen XML 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 pertandingan sepak bola pada pertandingan tertentu. Respons XML mengambil dalam 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. Karena itu, sangat diperlukan untuk:

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

Contoh berikut menunjukkan cara mengakses elemen <matches> di atas cuplikan dokumen:

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

Dengan sampel jadwal football:

<match status="..." category="..." ... >
  ...
</match>

Atribut dapat diambil, misalnya:

const status = matchElement.getAttribute('status').getValue();

Teks yang terdapat dalam elemen dapat dibaca menggunakan getText(), tetapi digabungkan di mana ada beberapa turunan teks dari suatu elemen. Pertimbangkan menggunakan getChildren() dan melakukan iterasi pada setiap turunan jika beberapa teks yang kemungkinan akan muncul.

Contoh Sportradar

Sportradar lengkap ini contoh menggambarkan mengambil detail pertandingan sepak bola, khususnya Liga Premier Inggris yang cocok. Sepak Bola API adalah salah satu dari berbagai macam feed olahraga yang ditawarkan oleh Sportradar.

Siapkan 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 MyAccount.

Sportradar memisahkan berbagai olahraga ke dalam API yang berbeda. Sebagai contoh, Anda dapat membeli akses ke football API tetapi tidak dapat membeli Tennis API. Masing-masing Aplikasi yang Anda buat dapat memiliki berbagai olahraga yang terkait dengannya, dan kunci yang berbeda.

1. Di bagian Aplikasi, klik Buat Aplikasi baru. Berikan aplikasi nama dan deskripsi, dan mengabaikan isian situs web.
2. Hanya pilih Issue a new key for football Trial Europe v2.
3. Klik Register Application.

Setelah berhasil, halaman yang berisi kunci API baru akan muncul.

1. Tempelkan contoh skrip ke skrip baru di Google Ads.
2. Ganti kunci API dalam listingan dengan kunci yang diperoleh di atas, lalu edit bidang alamat email.

Pemecahan masalah

Saat bekerja dengan API pihak ketiga, error dapat terjadi karena beberapa alasan, contoh:

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

Dalam semua kasus ini, dan yang lainnya, langkah pertama yang baik dalam mengidentifikasi penyebabnya masalahnya adalah memeriksa detail respons yang menyebabkan error.

Uraikan respons

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

Untuk mencegah perilaku ini, dan untuk memungkinkan pesan {i>error<i} dan {i>error<i} 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 respons yang diharapkan data, pertimbangkan bahwa:

  • Beberapa API memungkinkan spesifikasi kolom dan/atau format respons gunakan. Periksa dokumentasi API untuk mengetahui detailnya.
  • Sebuah API mungkin memiliki beberapa resource yang dapat dipanggil. Lihat dokumentasi untuk menentukan apakah sumber daya yang berbeda lebih sesuai untuk digunakan, dan akan mengembalikan data yang Anda butuhkan.
  • API mungkin telah berubah sejak kode ditulis. Lihat dokumentasi atau developer untuk klarifikasi.

• 400 Bad Request biasanya berarti bahwa ada sesuatu yang salah dalam pemformatan atau struktur permintaan yang dikirim ke server. Periksa dan membandingkannya dengan spesifikasi API untuk memastikan ekspektasi perusahaan. 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 sudah diperoleh dan diberikan sebagai token Bearer.
  • Untuk variasi lain tentang otorisasi, pastikan bahwa kredensial yang diperlukan untuk permintaan tersebut akan diberikan.

• 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 bahwa resource yang dirujuk ada (misalnya, jika file ada untuk API berbasis file).

Memeriksa permintaan

Memeriksa permintaan berguna jika respons API menunjukkan bahwa permintaan tidak aman membentuk, 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 mengembalikannya. Hal ini memungkinkan pengguna untuk memeriksa elemen permintaan untuk memastikan permintaan terlihat benar.

Misalnya, jika data formulir dalam permintaan Anda terdiri dari banyak string yang digabungkan bersama-sama, kesalahannya mungkin terletak pada fungsi yang Anda buat untuk menghasilkan formulir itu layanan otomatis dan data skalabel. Cara termudahnya:

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

akan memungkinkan Anda memeriksa elemen-elemen permintaan.

Mencatat permintaan dan respons

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

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

2. Tambahkan fungsi berikut ke bagian 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 Anda, detail semua permintaan dan respons dicatat ke konsol, memungkinkan {i>debugging<i} yang lebih mudah.