Pengantar
Dokumen ini ditujukan untuk developer yang ingin menulis library klien, plugin IDE, dan alat lainnya untuk berinteraksi dengan Google API. Layanan Discovery API Google memungkinkan Anda melakukan semua hal di atas dengan mengekspos metadata yang dapat dibaca mesin tentang Google API lainnya melalui API sederhana. Panduan ini menyediakan ringkasan setiap bagian dokumen Discovery, serta tips bermanfaat tentang cara menggunakan dokumen.
Semua panggilan ke API tidak diautentikasi, permintaan REST berbasis JSON yang menggunakan SSL, yaitu URL dimulai dengan https
.
Jika Anda tidak terbiasa dengan konsep Layanan Penemuan Google API, sebaiknya baca Memulai sebelum mulai membuat kode.
Format dokumen discovery
Bagian ini memberikan ringkasan Dokumen discovery.
Semua contoh di bawah menggunakan dokumen Discovery dari Google Cloud Service Management API. Anda dapat memuat dokumen Discovery untuk Google Cloud Service Management API dengan menjalankan permintaan GET
ini:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1
Format dokumen Discovery mencakup informasi yang termasuk dalam enam kategori utama:
- Deskripsi dasar API.
- Informasi Authentication untuk API.
- Detail resource dan skema yang menjelaskan data API.
- Detail tentang metode API.
- Informasi tentang fitur kustom yang didukung oleh API.
- Dokumentasi inline yang menjelaskan elemen utama API.
Setiap bagian dokumen Discovery ini dijelaskan di bawah. Lihat dokumentasi Referensi untuk mengetahui detail selengkapnya tentang setiap properti.
Deskripsi API Dasar
Dokumen Discovery berisi kumpulan properti khusus API:
"kind": "discovery#restDescription", "name": "servicemanagement", "version": "v1", "title": "Service Management API", "description": "Google Service Management allows service producers to publish their services on Google Cloud Platform so that they can be discovered and used by service consumers.", "protocol": "rest", "rootUrl": "https://servicemanagement.googleapis.com/. Root URL under which all API services live", "servicePath": "",
Properti API level ini mencakup detail tentang versi API tertentu, termasuk name
, version
, title
, dan description
. protocol
selalu memiliki nilai tetap rest
, karena API Discovery Service hanya mendukung metode RESTful untuk mengakses API.
Kolom servicePath
menunjukkan awalan jalur untuk versi API tertentu ini.
Autentikasi
Bagian auth
berisi detail tentang cakupan autentikasi OAuth 2.0 untuk API. Untuk mempelajari lebih lanjut cara menggunakan cakupan dengan OAuth 2.0, buka Menggunakan OAuth 2.0 untuk Mengakses Google API.
Bagian auth
berisi bagian oauth2
dan scopes
bertingkat. Bagian scopes
adalah pemetaan kunci/nilai dari nilai cakupan ke detail selengkapnya tentang cakupan:
"auth": { "oauth2": { "scopes": { "https://www.googleapis.com/auth/cloud-platform.read-only": { "description": "View your data across Google Cloud Platform services" }, "https://www.googleapis.com/auth/service.management.readonly": { "description": "View your Google API service configuration" }, "https://www.googleapis.com/auth/cloud-platform": { "description": "View and manage your data across Google Cloud Platform services" }, "https://www.googleapis.com/auth/service.management": { "description": "Manage your Google API service configuration" } } } }
Bagian auth
hanya menentukan cakupan untuk API tertentu. Untuk mempelajari bagaimana cakupan ini dikaitkan dengan metode API, lihat bagian Metode di bawah.
Referensi dan skema
Operasi API bertindak pada objek data yang disebut resources
. Dokumen Discovery dibuat berdasarkan konsep resource. Setiap dokumen Discovery memiliki bagian resources
tingkat atas yang mengelompokkan semua resource yang terkait dengan API. Misalnya, Google Cloud Service Management API memiliki resource services
dan resource operations
pada level teratas resources
, resource services
memiliki tiga sub-resource, yaitu configs
, rollouts
, dan consumers
:
"resources": { "services": { // Methods and sub-resources associated with the services resource "configs": { // Methods and sub-resources associated with the services.configs resource }, "rollouts": { // Methods and sub-resources associated with the services.rollouts resource }, "consumers": { // Methods and sub-resources associated with the services.consumers resource } }, "operations": { // Methods and sub-resources associated with the operations resource } }
Di dalam setiap bagian resource, terdapat metode yang terkait dengan resource tersebut. Misalnya, Google Cloud Service Management API memiliki tiga metode yang terkait dengan resource services.rollouts
: get
, list
, dan create
.
Skema memberi tahu Anda seperti apa resource di API. Setiap dokumen Discovery memiliki bagian schemas
tingkat atas, yang berisi pasangan nama/nilai ID skema untuk objek. ID skema bersifat unik untuk setiap API, dan digunakan untuk mengidentifikasi skema secara unik di bagian methods
dalam dokumen Discovery:
"schemas": { "Rollout": { // JSON Schema of the Rollout resource. } }
API Discovery Service menggunakan JSON Schema draf-03 untuk representasi skemanya. Berikut adalah cuplikan Skema JSON untuk resource URL, beserta resource respons sebenarnya:
Skema JSON Resource Peluncuran: | Respons Resource Peluncuran Sebenarnya: |
{ "Rollout": { "id": "Rollout", "type": "object", "description": "...", "properties": { "serviceName": { "type": "string", "description": "..." }, "rolloutId": { "type": "string", "description": "..." }, "status": { "type": "string", "enum": [ "ROLLOUT_STATUS_UNSPECIFIED", "IN_PROGRESS", "SUCCESS", "CANCELLED", "FAILED", "PENDING", "FAILED_ROLLED_BACK" ], "enumDescriptions": [ ... ], "description": "..." }, "trafficPercentStrategy": { "$ref": "TrafficPercentStrategy", "description": "..." }, "deleteServiceStrategy": { ... }, "createTime": { ... }, "createdBy": { ... } } } } |
{ "serviceName": "discovery.googleapis.com", "rolloutId": "2020-01-01R0", "status": "SUCCESS", "trafficPercentStrategy":{ "precentages":{ "2019-12-01R0": 70.00, "2019-11-01R0": 30.00 } } } |
Kolom yang dicetak tebal menunjukkan pemetaan antara Skema JSON dan respons yang sebenarnya.
Skema juga dapat berisi referensi ke skema yang lain. Jika Anda mem-build library klien, library ini dapat membantu Anda membuat model objek API secara efektif di class model data. Pada contoh Rollout
di atas, properti trafficPercentStrategy
sebenarnya merupakan referensi ke skema dengan ID TrafficPercentStrategy
. Jika Anda melihat bagian schemas
, Anda akan menemukan skema TrafficPercentStrategy
. Nilai skema ini dapat diganti untuk properti trafficPercentStrategy
dalam resource Rollout
(perhatikan bahwa sintaksis $ref
berasal dari spesifikasi Skema JSON).
Metode juga dapat mereferensikan skema saat menunjukkan isi permintaan dan responsnya. Lihat bagian Metode untuk detail selengkapnya.
Metode
Inti dari dokumen Discovery dibuat berdasarkan metode. Metode adalah operasi yang dapat dilakukan pada API. Anda akan menemukan bagian methods
di berbagai area dokumen Discovery, termasuk di level teratas (yang kami sebut metode API level) atau di level resources
.
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
Meskipun API mungkin memiliki metode API level, resource harus memiliki bagian methods
.
Setiap bagian methods
adalah peta kunci/nilai dari nama metode untuk detail lainnya tentang metode tersebut. Contoh di bawah mendokumentasikan tiga metode, get
, list
, dan create
:
"methods": { "get": { //details about the "get" method }, "list": { //details about the "list" method }, "create": { //details about the "create" method } }
Terakhir, setiap bagian metode akan merinci berbagai properti tentang metode tersebut. Berikut adalah contoh metode get
:
"get": { "id": "servicemanagement.services.rollouts.get", "path": "v1/services/{serviceName}/rollouts/{rolloutId}", "flatPath": "v1/services/{serviceName}/rollouts/{rolloutId}", "httpMethod": "GET", "description": "Gets a service configuration rollout.", "response": { "$ref": "Rollout" }, "parameters": { // parameters related to the method }, "parameterOrder": [ // parameter order related to the method ], "scopes": [ // OAuth 2.0 scopes applicable to this method ], "mediaUpload": { // optional media upload information }, },
Bagian ini berisi detail metode umum seperti ID
unik untuk mengidentifikasi metode, httpMethod
yang akan digunakan, dan path
metode (untuk detail tentang cara menggunakan properti path
guna menghitung URL metode lengkap, lihat bagian Membuat permintaan). Selain properti metode umum tersebut, ada beberapa properti yang menghubungkan metode ini dengan bagian lain dalam dokumen Discovery:
Cakupan
Bagian auth
yang ditentukan sebelumnya dalam dokumentasi ini berisi informasi tentang semua cakupan yang didukung oleh API tertentu. Jika metode mendukung salah satu cakupan ini, metode akan memiliki array cakupan. Terdapat satu entri dalam array ini untuk setiap cakupan yang didukung oleh metode. Misalnya, bagian scopes
dari metode get
Google Cloud Service Management API akan terlihat seperti ini:
"scopes": [ "https://www.googleapis.com/auth/cloud-platform", "https://www.googleapis.com/auth/cloud-platform.read-only", "https://www.googleapis.com/auth/service.management", "https://www.googleapis.com/auth/service.management.readonly" ]
Perhatikan bahwa pemilihan cakupan autentikasi yang akan digunakan dalam aplikasi Anda bergantung pada berbagai faktor seperti metode mana yang dipanggil dan parameter yang dikirim bersama metode tersebut. Oleh karena itu, keputusan cakupan mana yang akan digunakan diserahkan kepada developer. Penemuan hanya dokumen yang memiliki cakupan yang valid untuk sebuah metode.
Permintaan dan respons
Jika metode ini memiliki isi permintaan atau respons, masing-masing akan didokumentasikan di bagian request
atau response
. Dalam contoh get
di atas, metode ini memiliki isi response
:
"response": { "$ref": "Rollout" }
Sintaksis di atas menunjukkan bahwa isi respons ditentukan oleh Skema JSON dengan ID Rollout
. Skema ini dapat ditemukan di bagian skema tingkat atas. Baik isi permintaan maupun respons menggunakan sintaksis $ref
untuk merujuk pada skema.
Parameter
Jika metode memiliki parameter yang harus ditentukan oleh pengguna, parameter ini didokumentasikan di bagian parameters
tingkat metode. Bagian ini berisi pemetaan kunci/nilai dari nama parameter untuk mengetahui detail selengkapnya tentang parameter tersebut:
"parameters": { "serviceName": { "type": "string", "description": "Required. The name of the service.", "required": true, "location": "path" }, "rolloutId": { ... } }, "parameterOrder": [ "serviceName", "rolloutId" ]
Pada contoh di atas, ada dua parameter untuk metode get
:serviceName
dan rolloutId
. Parameter dapat masuk di path
atau URL query
; properti location
menunjukkan lokasi library klien yang harus menempatkan parameter.
Ada banyak properti lain yang mendeskripsikan parameter, termasuk data parameter type
(berguna untuk bahasa yang diketik dengan kuat), apakah parameternya required
, dan apakah parameternya adalah enum. Lihat Panduan Referensi untuk mengetahui detail selengkapnya tentang properti.
Urutan parameter
Ada banyak cara bagi library klien untuk menyusun antarmukanya. Salah satu caranya adalah dengan memiliki metode dengan setiap parameter API di tanda tangan metode. Namun, karena format JSON tidak berurutan, sulit untuk mengetahui secara terprogram cara mengurutkan parameter dalam tanda tangan metode. Array parameterOrder
menyediakan pengurutan parameter tetap untuk membuat permintaan. Array mencantumkan nama setiap parameter dalam urutan signifikan; dapat berisi jalur atau parameter kueri, tetapi setiap parameter dalam array diperlukan. Pada contoh di atas, tanda tangan metode Java akan terlihat seperti ini:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);
Nilai pertama dalam array parameterOrder
, serviceName
, juga merupakan elemen pertama dalam tanda tangan metode. Jika ada parameter lain di array parameterOrder
, parameter tersebut akan berada setelah parameter serviceName
. Karena array parameterOrder
hanya berisi parameter yang diperlukan, praktik yang baik adalah menyertakan cara bagi pengguna untuk menentukan parameter opsional. Contoh di atas melakukan ini dengan peta optionalParameters
.
Upload media
Jika metode mendukung media yang diupload, seperti gambar, audio, atau video, lokasi dan protokol yang didukung untuk mengupload media tersebut akan didokumentasikan di bagian mediaUpload
. Bagian ini berisi detail tentang protokol upload yang didukung, dan informasi tentang jenis media yang dapat diupload:
"supportsMediaUpload": true, "mediaUpload": { "accept": [ "image/*" ], "maxSize": "10MB", "protocols": { "simple": { "multipart": true, "path": "/upload/storage/v1beta1/b/{bucket}/o" }, "resumable": { "multipart": true, "path": "/resumable/upload/storage/v1beta1/b/{bucket}/o" } } }
Pada contoh di atas, properti supportsMediaUpload
adalah nilai boolean yang menentukan apakah metode tersebut mendukung media yang diupload. Jika nilainya benar, bagian mediaUpload
akan mendokumentasikan jenis media yang dapat diupload.
Properti accept
adalah daftar rentang media yang menentukan jenis MIME yang dapat diterima untuk diupload. Endpoint yang ditampilkan pada contoh di atas akan menerima format gambar apa pun.
Properti maxSize
memiliki ukuran maksimum upload. Nilainya adalah string dalam satuan MB, GB, atau TB. Pada contoh di atas, upload dibatasi hingga ukuran maksimum 10 MB. Perhatikan bahwa nilai ini tidak mencerminkan sisa kuota penyimpanan setiap pengguna untuk API tersebut. Jadi, meskipun upload kurang dari maxSize
, library klien harus tetap siap menangani upload yang gagal karena ruang penyimpanan tidak cukup.
Bagian protocols
mencantumkan protokol upload yang didukung oleh metode. Protokol simple
hanya memposting konten ke endpoint yang ditentukan dalam satu permintaan HTTP. Protokol resumable
menyiratkan bahwa endpoint yang diberikan dalam URI path
mendukung protokol upload yang dapat dilanjutkan. Jika properti multipart
adalah true
, endpoint akan menerima upload multibagian, yang berarti permintaan JSON dan media dapat digabungkan dalam isi mutlipart/terkait dan dikirim bersama. Perlu diperhatikan bahwa protokol simple
dan resumable
mungkin mendukung upload multibagian.
Properti path
adalah Template URI dan harus diperluas seperti properti path
untuk metode tersebut, seperti yang diuraikan di bagian Membuat permintaan.
Download media
Jika metode mendukung media yang didownload, seperti gambar, audio, atau video, hal tersebut akan ditunjukkan oleh parameter supportsMediaDownload
:
"supportsMediaDownload": true,
Saat mendownload media, Anda harus menetapkan parameter kueri alt
ke media
di URL permintaan.
Jika properti useMediaDownloadService
dari metode API adalah true
, sisipkan /download
sebelum servicePath
untuk menghindari pengalihan. Misalnya, jalur download adalah /download/youtube/v3/captions/{id}
jika penyambungan servicePath
dan path
adalah /youtube/v3/captions/{id}
. Sebaiknya buat URL download media dengan /download
meskipun useMediaDownloadService
salah.
Parameter umum
Dokumen Discovery level teratas berisi properti parameters
. Bagian ini mirip dengan bagian parameter untuk setiap metode, tetapi parameter ini dapat diterapkan ke metode apa pun di API.
Misalnya, metode get, sisipkan, atau cantumkan Google Cloud Service Management API dapat memiliki parameter prettyPrint
dalam parameter permintaan, yang akan memformat respons untuk semua metode tersebut dalam format yang dapat dibaca manusia. Berikut daftar parameter umum:
Parameter | Arti | Catatan | Keberlakuan |
---|---|---|---|
access_token |
Token OAuth 2.0 untuk pengguna saat ini. |
|
|
alt |
Format data untuk respons. |
|
|
callback |
Fungsi callback. |
| |
fields |
Pemilih yang menentukan subkumpulan kolom untuk disertakan dalam respons. |
|
|
key |
Kunci API. (WAJIB*) |
|
|
prettyPrint |
Menampilkan respons dengan identifikasi dan jeda baris. |
|
|
quotaUser |
Alternatif untuk userIp . |
|
|
userIp |
Alamat IP pengguna akhir yang panggilan API-nya dilakukan. |
|
Fitur
Ada beberapa kasus ketika API mendukung fitur kustom di luar cakupan dokumen Discovery lainnya. Ini dikumpulkan dalam array features
. Array fitur berisi label string untuk setiap fitur khusus yang didukung oleh API. Saat ini, dataWrapper
adalah satu-satunya fitur yang didukung, tetapi fitur lainnya mungkin didukung di masa mendatang.
"features": dataWrapper
Fitur dataWrapper
menunjukkan bahwa semua permintaan ke dan respons dari API digabungkan dalam objek JSON data
. Ini adalah fitur Google API versi lama, tetapi tidak digunakan lagi di masa mendatang. API berikut mendukung fitur dataWrapper
: Moderator v1 dan Terjemahan v2.
Sebagai developer library klien, jika API mendukung fitur "dataWrapper" Anda harus melakukan hal berikut:
- Berdasarkan permintaan: Gabungkan resource permintaan dalam objek JSON
data
. - Di respons: Temukan resource di dalam objek JSON
data
.
Skema dalam dokumen Discovery tidak berisi wrapper data, sehingga Anda harus menambahkan dan menghapusnya secara eksplisit. Misalkan ada API dengan resource bernama "Foo" yang terlihat seperti ini:
{ "id": 1, "foo": "bar" }
Sebelum menyisipkan resource ini menggunakan API, Anda harus menggabungkannya ke dalam elemen data:
{ "data": { "id": 1, "foo": "bar" } }
Di sisi lain, saat Anda mendapatkan respons dari API, respons ini juga berisi wrapper data:
{ "data": { "id": 1, "foo": "bar" } }
Untuk mendapatkan resource yang ditentukan oleh skema, Anda harus menghapus wrapper data:
{ "id": 1, "foo": "bar" }
Dokumentasi inline
Setiap dokumen Discovery dianotasi dengan sejumlah kolom description
yang menyediakan dokumentasi inline untuk API. Kolom description
dapat ditemukan untuk elemen API berikut:
- API itu sendiri
- Cakupan OAuth
- Skema resource
- Metode API
- Parameter metode
- Nilai yang dapat diterima untuk parameter tertentu
Kolom ini sangat berguna jika Anda ingin menggunakan Google API Discovery Service guna membuat dokumentasi yang dapat dibaca manusia untuk library klien, mis. JavaDoc.