Bu belge, Google API'leriyle etkileşim kurmak için istemci kitaplıkları, IDE eklentileri ve diğer araçları yazmak isteyen geliştiriciler için hazırlanmıştır. Google API'leri Discovery Hizmeti, diğer Google API'leri hakkında makine tarafından okunabilir meta verileri basit bir API aracılığıyla kullanıma sunarak yukarıdakilerin tümünü yapmanıza olanak tanır. Bu kılavuzda, Discovery belgesinin her bölümüne genel bir bakışın yanı sıra belgeyi kullanmayla ilgili faydalı ipuçları verilmektedir.
API'ye yapılan tüm çağrılar, kimliği doğrulanmamış, JSON tabanlı, SSL kullanan REST istekleridir. Diğer bir deyişle, URL'ler https ile başlar.
Keşif dokümanı biçimi
Bu bölümde, Discovery belgesine genel bir bakış sunulmaktadır.
Aşağıdaki tüm örneklerde Service Usage API'nin Discovery belgesi kullanılır.
Bu GET isteğini yürüterek Service Usage API'nin keşif dokümanını yükleyebilirsiniz:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1
Keşif dokümanının biçimi, altı ana kategoriye giren bilgileri içerir:
- API'nin temel açıklaması.
- API için kimlik doğrulama bilgileri.
- API'nin verilerini açıklayan kaynak ve şema ayrıntıları.
- API'nin yöntemleri hakkında ayrıntılar.
- API tarafından desteklenen özel özellikler hakkında bilgi.
- API'nin temel öğelerini açıklayan satır içi dokümanlar.
Bu Discovery dokümanı bölümlerinin her biri aşağıda açıklanmıştır.
Temel API Açıklaması
Discovery belgesi, API'ye özgü bir dizi özellik içerir. Bu özellikler mutlaka bu sırada veya keşif dokümanının aynı bölümünde görünmez:
"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"
Bu API düzeyi özellikleri, name, version, title ve description dahil olmak üzere bir API'nin belirli bir sürümüyle ilgili ayrıntıları içerir. API'lere erişmek için yalnızca RESTful yöntemleri destekleyen API'ler Keşif Hizmeti nedeniyle protocol her zaman rest sabit değerine sahiptir.
servicePath alanı, bu API sürümünün yol ön ekini gösterir.
Kimlik doğrulama
auth bölümünde, API'nin OAuth 2.0 kimlik doğrulama kapsamlarıyla ilgili ayrıntılar yer alır. Kapsamları OAuth 2.0 ile kullanma hakkında daha fazla bilgi edinmek için Google API'lerine Erişmek İçin OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.
auth bölümü, iç içe yerleştirilmiş bir oauth2 ve scopes bölümü içerir. scopes bölümü, kapsam değeri ile kapsam hakkında daha fazla ayrıntı arasındaki bir anahtar/değer eşlemesidir:
"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" } } } }
auth bölümü yalnızca belirli bir API'nin kapsamlarını tanımlar. Bu kapsamların bir API yöntemiyle nasıl ilişkilendirildiğini öğrenmek için aşağıdaki Yöntemler bölümüne bakın.
Kaynaklar ve şemalar
Bir API'nin işlemleri, resources adı verilen veri nesneleri üzerinde çalışır. Keşif dokümanı, kaynak kavramı üzerine kuruludur. Her Discovery belgesinde, API ile ilişkili tüm kaynakları gruplandıran üst düzey bir resources bölümü bulunur. Örneğin, Service Usage API'nin üst düzey resources altında bir services kaynağı ve bir operations kaynağı vardır:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
Her kaynak bölümünde, o kaynakla ilişkili yöntemler bulunur. Örneğin, Service Usage API'nin services kaynağıyla ilişkili altı yöntemi vardır: get, enable, disable, batchGet, batchEnable ve list.
Şemalar, bir API'deki kaynakların nasıl göründüğünü gösterir. Her Discovery belgesinde, şema kimliğinin nesneye ilişkin ad/değer çiftini içeren üst düzey bir schemas bölümü bulunur. Şema kimlikleri API başına benzersizdir ve Discovery belgesinin methods bölümündeki şemayı benzersiz bir şekilde tanımlamak için kullanılır. Örneğin, Hizmet Kullanımı API'si Discovery belgesindeki şemalardan bazıları aşağıda verilmiştir:
"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 } }
API'ler Keşif Hizmeti, şema gösterimleri için JSON
Schema draft-03'ü kullanır. Aşağıda, EnableServiceResponse kaynağının JSON şemasının bir snippet'i ve referans verdiği GoogleApiServiceusagev1Service yer almaktadır. Bu şemaların yanı sıra, Pub/Sub API'nin etkinleştirilmesi isteğine yönelik gerçek bir yanıtın bir bölümü de yer almaktadır (pubsub.googleapis.com).
EnableServiceResponse Kaynak JSON Şeması: |
Bir hizmeti etkinleştirmek için gerçek yanıt: |
"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" }, " |
"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": {} }, " |
Kalın olarak belirtilen alanlar, JSON şeması ile gerçek yanıt arasındaki eşlemeyi gösterir.
Bu örnekte gösterildiği gibi, şemalar diğer şemalara referanslar içerebilir. İstemci kitaplığı oluşturuyorsanız bu, API nesnelerini veri modeli sınıflarınızda etkili bir şekilde modellemenize yardımcı olabilir. Yukarıdaki EnableServiceResponse örneğinde, service özelliği, Service Usage API Discovery belgesindeki başka bir şema olan GoogleApiServiceusageV1Service kimlikli bir şemaya yapılan referanstır. EnableServiceResponse kaynağındaki GoogleApiServiceusageV1Service özelliğini GoogleApiServiceusageV1Service şemasının değeriyle değiştirebilirsiniz ($ref söz diziminin JSON şema spesifikasyonundan geldiğini unutmayın).
Yöntemler, istek ve yanıt gövdelerini belirtirken şemalara da başvurabilir. Daha fazla bilgi için Yöntemler bölümüne bakın.
Yöntemler
Keşif dokümanının temelinde yöntemler yer alır. Yöntemler, bir API'de gerçekleştirilebilecek işlemlerdir. methods bölümünü, üst düzey (API düzeyinde yöntemler olarak adlandırılır) veya resources düzeyinde olmak üzere Discovery belgesinin çeşitli alanlarında bulabilirsiniz.
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
Bir API'de API düzeyinde yöntemler olabilir ancak bir kaynakta mutlaka bir methods bölümü olmalıdır.
Her methods bölüm, yöntem adından bu yöntemle ilgili diğer ayrıntılara yönelik bir anahtar-değer eşlemesidir. Aşağıdaki örnekte üç yöntem (get, enable ve disable) belgelenmektedir:
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
Son olarak, her yöntemin bölümünde bu yöntemle ilgili çeşitli özellikler ayrıntılı olarak açıklanır. enable yönteminin bir örneğini aşağıda görebilirsiniz:
"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/[^/]+$" } } },
Bu bölümde, yöntemi tanımlamak için kullanılan benzersiz ID, kullanılacak httpMethod ve yöntemin path gibi genel yöntem ayrıntıları yer alır (path özelliğini kullanarak tam yöntem URL'sini nasıl hesaplayacağınızla ilgili ayrıntılar için İstek oluşturma bölümüne bakın). Bu genel yöntem özelliklerine ek olarak, yöntemi Discovery belgesindeki diğer bölümlere bağlayan birkaç özellik vardır:
Kapsamlar
Bu dokümanın önceki bölümlerinde tanımlanan auth bölümünde, belirli bir API tarafından desteklenen tüm kapsamlar hakkında bilgi verilmektedir. Bir yöntem bu kapsamların birini destekliyorsa kapsam dizisi içerir. Bu dizide, yöntem tarafından desteklenen her kapsam için bir giriş bulunur.
Uygulamanızda kullanılacak bir yetkilendirme kapsamı seçmenin, hangi yöntemlerin çağrıldığı ve yöntemle birlikte hangi parametrelerin gönderildiği gibi çeşitli faktörlere bağlı olduğunu unutmayın. Bu nedenle, hangi kapsamın kullanılacağına geliştirici karar verir. Bir yöntem için yalnızca hangi kapsamların geçerli olduğunu keşfedin.
İstek ve yanıt
Yöntemin istek veya yanıt metni varsa bunlar sırasıyla request
veya response bölümlerinde belgelenir. Örneğin, enable
yönteminde, request bölümünün içeriği, yöntemin isteğinin EnableServiceRequest kimlikli bir JSON şemasıyla tanımlandığını gösterir. Bu şemayı üst düzey şemalar bölümünde bulabilirsiniz.
Parametreler
Bir yöntemin kullanıcı tarafından belirtilmesi gereken parametreleri varsa bu parametreler, yöntem düzeyindeki parameters bölümünde belgelenir. Bu bölümde, parametre adının söz konusu parametreyle ilgili daha fazla ayrıntıyla eşlenmesi yer alır.
Örneğin, enable yöntemi için tek bir parametre vardır: name.
Parametreler path veya URL query'ye gidebilir. location özelliği, istemci kitaplığının parametreyi nereye yerleştirmesi gerektiğini gösterir.
Parametre verileri type (kesin türü belirlenmiş diller için yararlıdır), parametrenin required olup olmadığı ve parametrenin enum olup olmadığı dahil olmak üzere parametreyi açıklayan birçok başka özellik vardır. Bu özellikler hakkında daha fazla bilgi için bu API'nin referans belgelerine bakın.
Parametre sırası
İstemci kitaplıklarının arayüzlerini yapılandırmanın birçok yolu vardır. Bunun bir yolu, yöntem imzasında her API parametresinin bulunduğu bir yöntem kullanmaktır. Ancak JSON sıralanmamış bir biçim olduğundan, yöntem imzasındaki parametrelerin nasıl sıralanacağını programatik olarak bilmek zordur. parameterOrder dizisi, istekte bulunmak için sabit bir parametre sıralaması sağlar. Dizi, her parametrenin adını önem sırasına göre listeler. Dizi, yol veya sorgu parametreleri içerebilir ancak dizideki her parametre zorunludur.
Medya yükleme
Bir yöntem, resim, ses veya video gibi medya yüklemeyi destekliyorsa bu medyayı yüklemek için desteklenen konum ve protokoller mediaUpload bölümünde belgelenir. Bu bölümde, hangi yükleme protokollerinin desteklendiği ve hangi türde medyaların yüklenebileceği hakkında ayrıntılı bilgi verilmektedir.
enable yönteminde mediaUpload bölümü yok. Ancak, tipik bir mediaUpload bölümü aşağıdaki gibi görünebilir:
"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" } } }
Yukarıdaki örnekte supportsMediaUpload özelliği, yöntemin medya yüklemeyi destekleyip desteklemediğini belirleyen bir boolean değerdir. Değer doğruysa mediaUpload bölümünde yüklenebilecek medya türleri açıklanır.
accept özelliği, hangi MIME türlerinin yüklenmesinin kabul edilebilir olduğunu belirleyen bir medya aralıkları listesidir. Yukarıdaki örnekte gösterilen uç nokta, tüm resim biçimlerini kabul eder.
maxSize mülkü, yükleme için maksimum boyuta sahiptir. Değer, MB, GB veya TB birimlerinde bir dizedir. Yukarıdaki örnekte, yüklemeler maksimum 10 MB boyutla sınırlıdır.
Bu değerin, söz konusu API için tek bir kullanıcının kalan depolama alanı kotasını yansıtmadığını unutmayın. Bu nedenle, yükleme maxSize değerinden daha az olsa bile istemci kitaplığı, yetersiz alan nedeniyle başarısız olan bir yüklemeyi işlemeye hazır olmalıdır.
protocols bölümünde, bir yöntemin desteklediği yükleme protokolleri listelenir. simple protokolü, medyayı tek bir HTTP isteğiyle belirtilen uç noktaya POST eder. resumable protokolü, path URI'sinde verilen uç noktanın devam ettirilebilir yükleme protokolünü desteklediğini gösterir. multipart özelliği true ise uç nokta çok parçalı yüklemeleri kabul eder. Bu durumda hem JSON isteği hem de medya multipart/related gövdesinde birlikte sarmalanıp birlikte gönderilebilir. Hem simple hem de resumable protokollerinin çok parçalı yüklemeleri destekleyebileceğini unutmayın.
path özelliği bir URI şablonudur ve İstek oluşturma bölümünde belirtildiği gibi yöntem için path özelliği gibi genişletilmelidir.
Medya indirme
Bir yöntem, resim, ses veya video gibi medya indirmeyi destekliyorsa bu durum supportsMediaDownload parametresiyle belirtilir:
"supportsMediaDownload": true,
Medya indirirken istek URL'sinde alt sorgu parametresini media olarak ayarlamanız gerekir.
API yönteminin useMediaDownloadService özelliği true ise yönlendirmeyi önlemek için servicePath öğesinden önce /download öğesini ekleyin. Örneğin, servicePath ve path birleştirildiğinde /youtube/v3/captions/{id} elde ediliyorsa indirme yolu /download/youtube/v3/captions/{id} olur. useMediaDownloadService yanlış olsa bile medya indirme URL'sinin /download ile oluşturulması önerilir.
Yaygın parametreler
Üst düzey Discovery dokümanı bir parameters özelliği içerir. Bu bölüm, her yöntem için parametreler bölümüne benzer ancak bu parametreler API'deki herhangi bir yönteme uygulanabilir.
Örneğin, Service Usage API'nin get ve list yöntemleri, istek parametrelerinde prettyPrint parametresine sahip olabilir. Bu parametre, tüm bu yöntemler için yanıtı okunabilir bir biçimde düzenler. Sık kullanılan parametrelerin listesi aşağıda verilmiştir:
| Parametre | Anlamı | Notlar | Uygulanabilirlik |
|---|---|---|---|
access_token |
Mevcut kullanıcı için OAuth 2.0 jetonu. |
|
|
alt |
Yanıtın veri biçimi. |
|
|
callback |
Geri çağırma işlevi. |
|
|
fields |
Yanıtın hangi alanları içereceğini belirten seçici. |
|
|
key |
API anahtarı. (ZORUNLU) |
|
|
prettyPrint |
Girintiler ve satır sonları içeren yanıt döndürür. |
|
|
quotaUser |
userIp'ya alternatif. |
|
|
userIp |
API çağrısının yapıldığı son kullanıcının IP adresi. |
|
Satır içi dokümanlar
Her Discovery belgesi, API için satır içi doküman sağlayan bir dizi description alanıyla açıklama eklenmiş olarak gelir. description alanları aşağıdaki API öğeleri için kullanılabilir:
- API'nin kendisi
- OAuth kapsamları
- Kaynak şemaları
- API Yöntemleri
- Yöntem parametreleri
- Belirli parametreler için kabul edilebilir değerler
Bu alanlar, bir istemci kitaplığı için (ör. JavaDoc) insanlar tarafından okunabilir dokümanlar oluşturmak üzere Google API'leri Keşif Hizmeti'ni kullanmak istiyorsanız özellikle yararlıdır.