Membuat library klien

Pengantar

Anda dapat menggunakan Layanan Discovery Google API untuk membuat berbagai alat yang berbeda untuk digunakan dengan Google API. Namun, tujuan utama dokumen Discovery ini adalah agar Google dapat membuat library klien dalam berbagai bahasa pemrograman. Bagian ini menjelaskan cara membuat library klien kustom untuk Google API.

Library klien yang stabil dan memiliki fitur lengkap adalah alat rumit yang dapat memerlukan waktu berbulan-bulan untuk berkembang. Namun, petunjuk umum untuk membuat library klien sederhana untuk Google API dapat dibagi menjadi tiga langkah sederhana:

  1. Mengambil dokumen Discovery dan mengonstruksi platform API
  2. Menulis permintaan
  3. Melakukan panggilan dan mengambil respons

Langkah-langkah ini dijelaskan secara lebih detail di bagian berikut. Anda juga dapat melihat contoh klien API Sederhana di bagian Contoh untuk mengetahui cara petunjuk tersebut dipetakan ke kode.

Langkah 1: Ambil dokumen Discovery

Sebelum mulai mengimplementasikan library klien, ada beberapa persyaratan dasar yang memengaruhi cara Anda melanjutkan jalur pengembangan. Misalnya, bahasa pilihan Anda mungkin diketik atau tidak diketik; jika diketik, bahasa tersebut dapat diketik secara statis atau dinamis. Kode ini dapat dikompilasi atau ditafsirkan. Persyaratan ini akan memandu pendekatan Anda dalam menggunakan dan menggunakan dokumen Discovery.

Tugas pengembangan pertama adalah mengambil dokumen Discovery. Strategi Anda untuk menentukan kapan dokumen akan diambil ditentukan oleh persyaratan yang Anda identifikasi. Misalnya, dalam bahasa yang diketik secara statistik, Anda dapat mengambil dokumen Discovery di awal proses, lalu membuat kode untuk menangani API tertentu yang dijelaskan oleh dokumen Discovery. Untuk bahasa yang banyak diketik, Anda dapat membuat beberapa kode dan mem-build library yang dikompilasi. Untuk bahasa yang diketik secara dinamis, Anda dapat dengan lambat membuat struktur pemrograman antarmuka ke API dengan cepat saat permukaan pemrograman digunakan.

Langkah 2: Tulis permintaan

Pembuatan permintaan memerlukan dua langkah terpisah:

  1. Menulis isi permintaan.
  2. Membuat URL permintaan.

Jika ada, Anda perlu mengonversi isi permintaan, dari representasi yang sesuai bahasa, ke dalam format berkabel yang benar. Misalnya, di library klien Java, mungkin ada class untuk setiap jenis permintaan yang memungkinkan manipulasi jenis permintaan yang aman dari data permintaan dan dapat diserialisasi ke dalam JSON.

Pembuatan URL permintaan adalah proses yang sedikit lebih rumit.

Properti path dari setiap metode di API menggunakan sintaksis URI Template v04. Properti ini dapat berisi variabel, yang dikelilingi oleh kurung kurawal. Berikut adalah contoh properti path dengan variabel:

/example/path/var

Pada jalur di atas, var adalah variabel. Nilai untuk variabel ini berasal dari bagian parameters dokumen Discovery untuk metode tersebut. Setiap nama variabel memiliki nilai yang sesuai dalam objek parameters. Pada contoh di atas, terdapat parameter bernama var di bagian parameters (dan properti location-nya adalah path, untuk menunjukkan bahwa variabel tersebut merupakan variabel jalur).

Saat membuat permintaan, Anda harus mengganti nilai untuk var ke URL. Misalnya, jika pengguna library membuat pilihan yang menetapkan var ke nilai foo, URL baru akan menjadi /example/path/foo.

Perhatikan juga bahwa properti path adalah URI relatif. Untuk menghitung URI mutlak, ikuti langkah-langkah berikut:

  1. Ambil properti rootUrl dari tingkat teratas dokumen Discovery.
    Misalnya, properti rootUrl dalam dokumen Discovery untuk Google Cloud Service Management API adalah:

    https://servicemanagement.googleapis.com/

  2. Ambil servicePath dari tingkat teratas dokumen Discovery.
    Misalnya, properti servicePath dalam dokumen Discovery untuk Google Cloud Service Management API kosong.

  3. Gabungkan untuk mendapatkan:

    https://servicemanagement.googleapis.com/

  4. Ambil properti path, luaskan sebagai Template URI, dan gabungkan hasil perluasan tersebut dengan URI dari langkah sebelumnya.
    Misalnya, dalam metode layanan get Google Cloud Service Management API, nilai properti path adalah v1/services/{serviceName}. Jadi, URI lengkap untuk metode ini adalah:

    https://servicemanagement.googleapis.com/v1/services/{serviceName}

Kunci API diperlukan untuk memanggil Google Cloud Service Management API. Jadi, setelah menerapkan kunci API, URI lengkap untuk mendapatkan definisi layanan dari Layanan Penemuan API adalah:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

Langkah 3: Lakukan panggilan dan tangani respons

Setelah mengirim permintaan, Anda perlu melakukan deserialisasi respons ke dalam representasi bahasa yang sesuai, dengan memperhatikan penanganan kondisi error yang bisa terjadi — baik dalam transpor HTTP dasar maupun pesan error yang dihasilkan dari layanan API. Format error didokumentasikan sebagai bagian dari Panduan Gaya JSON Google.

Contoh

Untuk beberapa contoh nyata alat dan library klien yang telah diterapkan menggunakan Layanan Discovery Google API, lihat dokumen Library dan Sampel. Selain itu, bagian berikut ini memberikan contoh sederhana library klien API.

Klien API sederhana

Di bawah ini adalah contoh library klien sangat sederhana yang ditulis dengan Python3 . Klien membuat antarmuka untuk berinteraksi dengan API Pengelolaan Layanan Google Cloud, lalu mendapatkan definisi layanan Layanan Penemuan API menggunakan antarmuka tersebut.

Peringatan: kode di bawah ini adalah versi library klien standar yang disederhanakan secara signifikan. Ini adalah implementasi tidak lengkap yang disediakan untuk mendemonstrasikan beberapa aspek dalam mem-build library klien. Kode ini bukan kode siap produksi.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + discovery['servicePath']

class Collection(object): pass

def createNewMethod(name, method):
  # Step 2.b Compose request
  def newMethod(**kwargs):
    body = kwargs.pop('body', None)
    url = urllib.parse.urljoin(BASE_URL, uritemplate.expand(method['path'], kwargs))
    for pname, pconfig in method.get('parameters', {}).items():
      if pconfig['location'] == 'path' and pname in kwargs:
        del kwargs[pname]
    if kwargs:
      url = url + '?' + urllib.parse.urlencode(kwargs)
    return h.request(url, method=method['httpMethod'], body=body,
                     headers={'content-type': 'application/json'})

  return newMethod

# Step 3.a: Build client surface
def build(discovery, collection):
  for name, resource in discovery.get('resources', {}).items():
    setattr(collection, name, build(resource, Collection()))
  for name, method in discovery.get('methods', {}).items():
    setattr(collection, name, createNewMethod(name, method))
  return collection

# Step 3.b: Use the client
service = build(discovery, Collection())
print (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

Komponen utama klien ini adalah:

  • Langkah 1: Ambil dokumen Discovery.
    Dokumen Discovery untuk Google Cloud Service Management API diambil dan diuraikan menjadi struktur data. Karena Python adalah bahasa yang diketik secara dinamis, dokumen Discovery dapat diambil saat runtime.
  • Langkah 2.a: Buat URI dasar.
    URI dasar dihitung.
  • Langkah 2.b: Tulis permintaan.
    Saat metode dipanggil di koleksi, Template URI akan diperluas dengan parameter yang diteruskan ke metode, dan parameter dengan lokasi query dimasukkan ke dalam parameter kueri URL. Terakhir, permintaan dikirim ke URL yang telah disusun menggunakan metode HTTP yang ditentukan dalam dokumen Discovery.
  • Langkah 3.a: Build platform klien.
    Platform klien dibuat secara menurun secara rekursif pada dokumen Discovery yang diuraikan. Untuk setiap metode di bagian methods, metode baru dilampirkan ke objek Collection. Karena koleksi dapat ditempatkan, kami mencari resources dan membuat objek Collection secara rekursif untuk semua anggotanya jika ditemukan. Setiap koleksi bertingkat juga dilampirkan sebagai atribut ke objek Collection.
  • Langkah 3.b: Gunakan klien.
    Ini menunjukkan cara permukaan API yang dibuat digunakan. Pertama-tama, objek layanan dibuat dari dokumen Discovery, lalu definisi layanan API Discovery Service diambil melalui Google Cloud Service Management API.