Halaman ini diterjemahkan oleh Cloud Translation API.

Menggunakan Discovery API

Dokumen ini ditujukan bagi developer yang ingin menulis library klien, plugin IDE, dan alat lainnya untuk berinteraksi dengan Google API. Layanan Penemuan Google API memungkinkan Anda melakukan semua hal di atas dengan mengekspos metadata yang dapat dibaca mesin tentang Google API lainnya melalui API sederhana. Panduan ini memberikan ringkasan tentang setiap bagian dokumen Discovery, serta tips bermanfaat tentang cara menggunakan dokumen.

Semua panggilan ke API adalah permintaan REST berbasis JSON yang tidak diautentikasi dan menggunakan SSL—dengan kata lain, URL dimulai dengan https.

Format dokumen Discovery

Bagian ini memberikan ringkasan tentang dokumen Discovery.

Semua contoh di bawah menggunakan dokumen Discovery dari Service Usage API. Anda dapat memuat Dokumen penemuan untuk Service Usage API dengan menjalankan permintaan GET ini:

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1

Format dokumen Discovery mencakup informasi yang terbagi dalam enam kategori utama:

Deskripsi dasar API.
Informasi Autentikasi 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.

Deskripsi API Dasar

Dokumen Discovery berisi kumpulan properti khusus API. Properti ini tidak selalu muncul dalam urutan ini, atau di bagian yang sama dalam dokumen penemuan:

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

Properti level API 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": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

Bagian auth hanya menentukan cakupan untuk API tertentu. Untuk mempelajari cara 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 level teratas yang mengelompokkan semua resource yang terkait dengan API. Misalnya, Service Usage API memiliki resource services dan resource operations di bagian resources tingkat atas:

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

Di dalam setiap bagian resource terdapat metode yang terkait dengan resource tersebut. Misalnya, Service Usage API memiliki enam metode yang terkait dengan resource services: get, enable, disable, batchGet, batchEnable, dan list.

Skema memberi tahu Anda tampilan resource dalam API. Setiap dokumen Discovery memiliki bagian schemas tingkat atas, yang berisi pasangan nama/nilai ID skema ke objek. ID skema bersifat unik per API, dan digunakan untuk mengidentifikasi skema secara unik di bagian methods dokumen Discovery. Misalnya, berikut beberapa skema dalam dokumen Penemuan API Penggunaan Layanan:

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

Layanan Penemuan API menggunakan Skema JSON draf-03 untuk representasi skemanya. Berikut adalah cuplikan Skema JSON untuk resource EnableServiceResponse, beserta GoogleApiServiceusagev1Service yang dirujuknya. Bersama skema ini adalah bagian dari respons sebenarnya untuk permintaan guna mengaktifkan Pub/Sub API (pubsub.googleapis.com).

EnableServiceResponse Skema JSON Resource: Respons sebenarnya untuk mengaktifkan layanan:

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

Kolom yang dicetak tebal menunjukkan pemetaan antara Skema JSON dan respons sebenarnya.

Seperti yang ditunjukkan dalam contoh ini, skema dapat berisi referensi ke skema lain. Jika Anda mem-build library klien, hal ini dapat membantu Anda membuat model objek API secara efektif dalam class model data Anda. Pada contoh EnableServiceResponse di atas, properti service adalah referensi ke skema dengan ID GoogleApiServiceusageV1Service, skema lain dalam dokumen Discovery API Penggunaan Layanan. Anda dapat mengganti properti GoogleApiServiceusageV1Service di resource EnableServiceResponse dengan nilai skema GoogleApiServiceusageV1Service (perhatikan bahwa sintaksis $ref berasal dari spesifikasi Skema JSON).

Metode juga dapat mereferensikan skema saat menunjukkan isi permintaan dan responsnya. Lihat bagian Metode untuk mengetahui detail selengkapnya.

Metode

Inti 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 tingkat teratas (yang kami sebut metode tingkat API) atau di tingkat resources.

"methods": {
  // API-level methods
}
"resources": {
  "resource1": {
    "methods": {
      // resource-level methods
    }
    "resources": {
      "nestedResource": {
        "methods": {
          // methods can even be found in nested-resources
        }
      }
    }
  }
}

Meskipun API dapat memiliki metode tingkat API, resource harus memiliki bagian methods.

Setiap bagian methods adalah peta nilai kunci dari nama metode ke detail lain tentang metode tersebut. Contoh di bawah mendokumentasikan tiga metode, get, enable, dan disable:

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

Terakhir, setiap bagian metode menjelaskan berbagai properti tentang metode tersebut. Berikut adalah contoh metode enable:

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

Bagian ini berisi detail metode umum seperti ID unik untuk mengidentifikasi metode, httpMethod yang akan digunakan, dan path metode (untuk mengetahui detail tentang cara menggunakan properti path untuk menghitung URL metode lengkap, lihat bagian Membuat permintaan). Selain properti metode umum ini, ada beberapa properti yang menghubungkan metode 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 mendukung salah satu cakupan ini, metode akan memiliki array cakupan. Ada satu entri dalam array ini untuk setiap cakupan yang didukung oleh metode.

Perhatikan bahwa memilih cakupan autentikasi yang akan digunakan dalam aplikasi Anda bergantung pada berbagai faktor seperti metode yang dipanggil dan parameter yang dikirim bersama metode tersebut. Oleh karena itu, keputusan cakupan yang akan digunakan diserahkan kepada developer. Discovery hanya mendokumentasikan cakupan yang valid untuk suatu metode.

Permintaan dan respons

Jika metode memiliki isi permintaan atau respons, keduanya akan didokumentasikan di bagian request atau response. Misalnya, untuk metode enable, konten bagian request menunjukkan bahwa permintaan metode ditentukan oleh skema JSON dengan ID EnableServiceRequest. Skema ini dapat ditemukan di bagian skema tingkat teratas.

Parameter

Jika metode memiliki parameter yang harus ditentukan oleh pengguna, parameter ini didokumentasikan di bagian parameters tingkat metode. Bagian ini berisi pemetaan kunci/nilai nama parameter ke detail selengkapnya tentang parameter tersebut.

Misalnya, ada satu parameter untuk metode enable: name. Parameter dapat ditempatkan di path atau query URL; properti location menunjukkan tempat library klien harus menempatkan parameter.

Ada banyak properti lain yang menjelaskan parameter, termasuk data parameter type (berguna untuk bahasa dengan jenis yang kuat), apakah parameter tersebut required, dan apakah parameter tersebut merupakan enum. Lihat dokumentasi referensi untuk API ini guna mengetahui detail selengkapnya tentang properti ini.

Urutan parameter

Ada banyak cara bagi library klien untuk menyusun antarmukanya. Salah satu caranya adalah dengan memiliki metode dengan setiap parameter API dalam tanda tangan metode. Namun, karena JSON adalah format tidak teratur, sulit untuk mengetahui secara terprogram cara mengurutkan parameter dalam tanda tangan metode. Array parameterOrder memberikan pengurutan parameter tetap untuk membuat permintaan. Array mencantumkan nama setiap parameter dalam urutan signifikansi; array dapat berisi parameter jalur atau kueri, tetapi setiap parameter dalam array diperlukan.

Upload media

Jika metode mendukung upload media, 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.

Metode enable tidak berisi bagian mediaUpload. Namun, bagian mediaUpload standar mungkin terlihat seperti berikut:

"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 mendukung upload media. Jika nilainya benar, bagian mediaUpload akan mendokumentasikan jenis media yang dapat diupload.

Properti accept adalah daftar rentang media yang menentukan jenis mime mana yang dapat diupload. Endpoint yang ditampilkan dalam 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 kuota penyimpanan yang tersisa untuk setiap pengguna untuk API tersebut, jadi meskipun upload kurang dari maxSize, library klien tetap harus siap menangani upload yang gagal karena ruang penyimpanan tidak memadai.

Bagian protocols mencantumkan protokol upload yang didukung metode. Protokol simple hanya mem-POST media ke endpoint tertentu 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 multibagian/terkait dan dikirim bersama-sama. Perhatikan bahwa protokol simple dan resumable dapat mendukung upload multibagian.

Properti path adalah Template URI dan harus diperluas seperti properti path untuk metode, seperti yang diuraikan di bagian Membuat permintaan.

Download media

Jika metode mendukung download media, seperti gambar, audio, atau video, hal tersebut ditunjukkan oleh parameter supportsMediaDownload:

"supportsMediaDownload": true,

Saat mendownload media, Anda harus menetapkan parameter kueri alt ke media di URL permintaan.

Jika properti useMediaDownloadService metode API adalah true, masukkan /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 bernilai salah.

Catatan: Satu metode API diizinkan untuk mendukung download dan upload media. Logika konstruksi URL permintaan untuk upload dan download media berfungsi secara independen dan tidak saling mengganggu. Akibatnya, metode API tersebut akan memiliki satu URL /download/... untuk download media dan satu URL /upload/... untuk upload media. Namun, Anda tidak dapat melakukan upload dan download media dalam satu permintaan.

Parameter umum

Dokumen Discovery tingkat 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 dan list dari Service Usage API dapat memiliki parameter prettyPrint dalam parameter permintaan, yang akan memformat respons untuk semua metode tersebut dalam format yang dapat dibaca manusia. Berikut adalah daftar parameter umum:

Parameter	Arti	Catatan	Penerapan
`access_token`	Token OAuth 2.0 untuk pengguna saat ini.	Salah satu kemungkinan cara untuk memberikan token OAuth 2.0.
`alt`	Format data untuk respons.	Nilai yang valid: `json`, `atom`, `csv`. Nilai default: bervariasi per API. Tidak semua nilai tersedia untuk setiap API.	Berlaku untuk semua operasi untuk semua resource.
`callback`	Fungsi callback.	Nama fungsi callback JavaScript yang menangani respons. Digunakan dalam permintaan JSON-P JavaScript.
`fields`	Pemilih yang menentukan subset kolom yang akan disertakan dalam respons.	Gunakan untuk performa yang lebih baik.
`key`	Kunci API. (WAJIB)	Wajib diisi kecuali jika Anda memberikan token OAuth 2.0. Kunci API mengidentifikasi project Anda dan memberi Anda akses, kuota, dan laporan API. Dapatkan kunci API project Anda dari konsol API.
`prettyPrint`	Menampilkan respons dengan indentasi dan baris baru.	Menampilkan respons dalam format yang dapat dibaca manusia jika `true`. Nilai default: bervariasi per API. Jika `false`, ukuran payload respons dapat dikurangi, yang mungkin menghasilkan performa yang lebih baik di beberapa lingkungan.
`quotaUser`	Alternatif untuk `userIp`.	Memungkinkan Anda menerapkan kuota per pengguna dari aplikasi sisi server meskipun alamat IP pengguna tidak diketahui. Hal ini dapat terjadi, misalnya, dengan aplikasi yang menjalankan tugas cron di App Engine atas nama pengguna. Anda dapat memilih string arbitrer apa pun yang secara unik mengidentifikasi pengguna, tetapi dibatasi hingga 40 karakter. Mengganti `userIp` jika keduanya disediakan. Pelajari lebih lanjut cara membatasi penggunaan.
`userIp`	Alamat IP pengguna akhir yang melakukan panggilan API.	Memungkinkan Anda menerapkan kuota per pengguna saat memanggil API dari aplikasi sisi server. Pelajari lebih lanjut cara membatasi penggunaan.

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 Layanan Penemuan Google API untuk membuat dokumentasi yang dapat dibaca manusia untuk library klien—misalnya, JavaDoc.

Menggunakan Discovery API Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Format dokumen Discovery

Deskripsi API Dasar

Autentikasi

Referensi dan skema

Metode

Cakupan

Permintaan dan respons

Parameter

Upload media

Download media

Parameter umum

Dokumentasi inline

Menggunakan Discovery API