Halaman ini diterjemahkan oleh Cloud Translation API.

Mem-build library klien
Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

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

Library klien yang stabil dan lengkap fiturnya adalah alat rumit yang dapat memerlukan waktu berbulan-bulan untuk dikembangkan. Namun, petunjuk umum untuk mem-build library klien sederhana untuk Google API dapat dibagi menjadi tiga langkah sederhana:

Mengambil dokumen Discovery dan membuat platform API
Membuat permintaan
Melakukan panggilan dan mengambil respons

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

Mengambil dokumen Discovery

Sebelum Anda mulai menerapkan library klien, ada beberapa persyaratan dasar yang memengaruhi cara Anda melanjutkan jalur pengembangan. Misalnya, bahasa pemrograman pilihan Anda dapat berupa berjenis atau tidak berjenis; jika berjenis, bahasa tersebut dapat berjenis statis atau dinamis. Kode ini dapat dikompilasi atau ditafsirkan. Persyaratan ini akan memandu pendekatan Anda untuk menggunakan dan memanfaatkan dokumen Discovery.

Tugas pengembangan pertama adalah mengambil dokumen Discovery. Strategi Anda untuk menentukan waktu pengambilan dokumen ditentukan oleh persyaratan yang Anda identifikasi. Misalnya, dalam bahasa dengan jenis statis, Anda dapat mengambil dokumen Discovery di awal proses, lalu membuat kode untuk menangani API tertentu yang dijelaskan oleh dokumen Discovery. Untuk bahasa dengan jenis yang kuat, Anda dapat membuat beberapa kode dan mem-build library yang dikompilasi. Untuk bahasa dengan jenis dinamis, Anda dapat membuat struktur pemrograman secara lambat untuk berinteraksi dengan API secara langsung saat platform pemrograman digunakan.

Menulis permintaan

Menulis permintaan melibatkan dua langkah terpisah:

Membuat isi permintaan.
Membuat URL permintaan.

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

Pembuatan URL permintaan adalah proses yang sedikit lebih rumit.

Properti path dari setiap metode di API menggunakan sintaksis Template URI v04. Properti ini dapat berisi variabel, yang diapit oleh tanda 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, ada parameter bernama var di bagian parameters (dan properti location-nya adalah path, untuk menunjukkan bahwa parameter tersebut adalah variabel jalur).

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

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

Jika Anda mengetahui lokasi (wilayah) Anda, dan dokumen Discovery memiliki properti endpoints, periksa apakah lokasi Anda ada dalam daftar endpoints. Jika ya, ambil endpointUrl dari daftar endpoints yang location-nya cocok dengan location Anda.
Jika tidak ada properti endpoints dalam dokumen Discovery atau lokasi Anda tidak ada dalam daftar endpoints atau Anda ingin menargetkan endpoint global, ambil properti rootUrl dari tingkat teratas dokumen Discovery.

Misalnya, properti rootUrl dalam Dokumen penemuan untuk Service Usage API adalah:
```
https://serviceusage.googleapis.com/
```
Ambil servicePath dari tingkat teratas dokumen Discovery. Misalnya, properti servicePath dalam dokumen Penemuan untuk Service Usage API kosong.
Gabungkan keduanya untuk mendapatkan:
```
https://serviceusage.googleapis.com/
```
Ambil properti path, luaskan sebagai Template URI, dan gabungkan hasil perluasan tersebut dengan URI dari langkah sebelumnya. Misalnya, dalam metode serviceusage.services.enable ServiceUsage API v1, nilai properti path adalah v1/{+name}:enable. Jadi, URI lengkap untuk metode tersebut adalah:
```
https://serviceusage.googleapis.com/v1/{+name}:enable
```

Anda tidak memerlukan kunci API untuk memanggil Service Usage API. Namun, jika API yang Anda panggil memerlukan kunci API, Anda dapat menambahkan kunci API ke string kueri URI:

REQUEST_URI?key=API_KEY

Melakukan panggilan dan menangani respons

Setelah mengirim permintaan, Anda perlu mendeserialisasi respons ke dalam representasi bahasa yang sesuai, dengan berhati-hati menangani kondisi error yang dapat terjadi—baik dalam transpor HTTP yang mendasarinya maupun pesan error yang dihasilkan dari layanan API. Format error didokumentasikan sebagai bagian dari Panduan Gaya JSON Google.

Contoh

Bagian berikut memberikan contoh sederhana library klien API.

Klien Simple API

Berikut adalah contoh library klien yang sangat sederhana yang ditulis dalam Python3. Klien membuat antarmuka untuk berinteraksi dengan Service Usage API, lalu menggunakan antarmuka tersebut untuk mengaktifkan Compute Engine API (compute.googleapis.com) di project my-project.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += 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 (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

Komponen penting klien adalah:

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