Giriş
Bu doküman istemci kitaplıkları, IDE eklentileri ve Google API'leri ile etkileşimde bulunmak için kullanılan diğer araçları yazmak isteyen geliştiriciler için hazırlanmıştır. Google API'leri Keşif Hizmeti, basit bir API aracılığıyla diğer Google API'leri hakkında makine tarafından okunabilen meta verileri göstererek yukarıdakilerin hepsini yapmanızı sağlar. Bu kılavuzda Discovery dokümanının her bölümüne genel bir bakışın yanı sıra dokümanı kullanma hakkında yardımcı ipuçları verilmiştir.
API'ye yapılan tüm çağrılar SSL kullanan, yani JSON tabanlı, REST istekleridir (yani URL'ler https ile başlar).
Google API'leri Keşif Hizmeti kavramları hakkında bilginiz yoksa, kodlamaya başlamadan önce Başlarken bölümünü okumanız gerekir.
Keşif dokümanı biçimi
Bu bölümde Discovery dokümanına genel bir bakış sunulmaktadır.
Aşağıdaki tüm örneklerde Google Cloud Service Management API'nin Discovery dokümanı kullanılmaktadır. Bu GET isteğini yürüttüğünüzde Google Cloud Service Management API için Keşif dokümanını yükleyebilirsiniz:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1Keş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 verilerini açıklayan kaynak ve şema ayrıntıları.
- API yöntemleri ile ilgili ayrıntılar.
- API tarafından desteklenen tüm ö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. Her bir mülk hakkında ayrıntılı bilgi için Referans belgelerini inceleyin.
Temel API Açıklaması
Keşif dokümanı, API'ye özgü bir grup özellik içerir:
"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": "",
Bu API düzeyi özellikleri; name, version, title ve description gibi belirli bir API sürümüyle ilgili ayrıntıları içerir. API Discovery Service, API'lere yalnızca RESTful yöntemlerini desteklediği için protocol her zaman sabit bir rest değerine sahiptir.
servicePath alanı, bu API sürümü için yol ön ekini belirtir.
Kimlik doğrulama
auth bölümünde, API'ye yönelik OAuth 2.0 kimlik doğrulama kapsamlarıyla ilgili ayrıntılar yer alır. OAuth 2.0 ile kapsamların nasıl kullanılacağı hakkında daha fazla bilgi edinmek için Google API'lerine Erişmek için OAuth 2.0'ı Kullanma sayfasını ziyaret edin.
auth bölümünde, iç içe yerleştirilmiş bir oauth2 ve scopes bölümü bulunuyor. scopes bölümü, kapsam değerinden kapsamla ilgili daha fazla ayrıntı içeren bir anahtar/değer eşlemesidir:
"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"
}
}
}
}
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
API işlemleri resources adlı veri nesnelerini temel alır. Discovery dokümanı, kaynak kavramına göre oluşturulmuştur. Her keşif dokümanının, API ile ilişkili tüm kaynakları gruplandıran üst düzey bir resources bölümü vardır. Örneğin, Google Cloud Service Management API'sinin bir services kaynağı ve üst düzey resources altında bir operations kaynağı, services kaynağının configs, rollouts ve consumers olmak üzere üç alt kaynağı vardır:
"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
}
}
Her kaynak bölümünün içinde, söz konusu kaynakla ilişkili yöntemler bulunur. Örneğin, Google Cloud Service Management API'sinin services.rollouts kaynağıyla ilişkilendirilmiş üç yöntemi vardır: get, list ve create.
Şemalar API'deki kaynakların neye benzediğini gösterir. Her Discovery dokümanında, itiraz edilecek şema kimliği için bir ad/değer çifti içeren üst düzey bir schemas bölümü vardır. Şema kimlikleri her API için benzersizdir ve Discovery dokümanının methods bölümündeki şemayı benzersiz bir şekilde tanımlamak için kullanılır:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
API Discovery Hizmeti, şema temsilleri için JSON Schema taslağı-03'u kullanır. Aşağıda, Url kaynağı için JSON Şeması snippet'inin yanı sıra gerçek bir yanıt kaynağı verilmiştir:
| Kullanıma Sunma Kaynak JSON Şeması: | Kullanıma Sunma Kaynak Yanıtı: |
{
"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
}
}
}
|
Kalın harflerle yazılmış alanlar, JSON şeması ile gerçek yanıt arasındaki eşlemeyi gösterir.
Şemalar diğer şemalara referanslar da içerebilir. İstemci kitaplığı derliyorsanız bu işlem, veri modeli sınıflarınızda bir API'nin nesnelerini etkili bir şekilde modellemenize yardımcı olabilir. Yukarıdaki Rollout örneğinde trafficPercentStrategy özelliği aslında TrafficPercentStrategy kimliğine sahip bir şemanın referansıdır. schemas bölümüne baktığınızda TrafficPercentStrategy şemasını görürsünüz. Bu şemanın değeri, Rollout kaynağındaki trafficPercentStrategy özelliği ile değiştirilebilir ($ref söz diziminin JSON Şema spesifikasyonundan geldiğini unutmayın).
Yöntemler, istek ve yanıt gövdelerini belirtirken şemalara da referans verebilir. Daha ayrıntılı bilgi için Yöntemler bölümüne bakın.
Yöntemler
Discovery dokümanının temeli yöntemler üzerine kurulmuştur. Yöntemler, bir API'de gerçekleştirilebilecek işlemlerdir. methods bölümünü, üst düzey (API düzeyi yöntemleri olarak adlandırılır) veya resources düzeyi de dahil olmak üzere Discovery dokümanının ç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 kaynağın methods bölümü olmalıdır.
Her methods bölümü, yöntem adından söz konusu yöntemle ilgili diğer ayrıntılara bir anahtar/değer eşlemesidir. Aşağıdaki örnekte get, list ve create olmak üzere üç yöntem gösterilmiştir:
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Son olarak, her yöntem bölümünde o yöntemle ilgili çeşitli özellikler ayrıntılı olarak verilir. get yönteminin bir örneğini burada görebilirsiniz:
"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 },
},
Bu bölümde, yöntemi tanımlamak için benzersiz bir ID, kullanılacak httpMethod ve yöntemin path gibi genel yöntem ayrıntıları yer alır (tam yöntem URL'sini hesaplamak için path özelliğinin nasıl kullanılacağıyla 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 dokümanındaki diğer bölümlere bağlayan birkaç özellik vardır:
Nişan dürbünleri
Bu dokümanın önceki bölümlerinde tanımlanan auth bölümü, belirli bir API tarafından desteklenen tüm kapsamlar hakkında bilgi içerir. Bir yöntem bu kapsamlardan birini destekliyorsa yöntemin bir kapsam dizisi olur. Yöntem tarafından desteklenen her kapsam için bu dizide bir giriş vardır. Örneğin, Google Cloud Service Management API get yönteminin scopes bölümü şu şekilde görünür:
"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" ]
Uygulamanızda kullanılacak kimlik doğrulama kapsamını seçmenin, hangi yöntemlerin çağrıldığı ve hangi parametrelerin yöntemle birlikte gönderildiği gibi çeşitli faktörlere bağlı olduğunu unutmayın. Bu nedenle, hangi kapsamın kullanılacağına karar veren geliştiriciye bırakılacaktır. Yalnızca bir yöntem için geçerli olan kapsamlar keşif amaçlıdır.
İstek ve yanıt
Yöntemde bir istek veya yanıt gövdesi varsa bunlar sırasıyla request veya response bölümlerinde açıklanmıştır. Yukarıdaki get örneğinde yöntem response gövdesine sahiptir:
"response": {
"$ref": "Rollout"
}
Yukarıdaki söz dizimi, yanıt gövdesinin Rollout kimliğine sahip bir JSON şeması tarafından tanımlandığını gösterir. Bu şema, üst düzey şemalar bölümünde bulunabilir. Hem istek hem de yanıt gövdeleri, şemalara atıfta bulunmak için $ref söz dizimini kullanır.
Parametreler
Bir yöntemde, kullanıcı tarafından belirtilmesi gereken parametreler varsa bu parametreler, yöntem düzeyindeki parameters bölümünde açıklanmıştır. Bu bölümde, parametre adının söz konusu parametreyle ilgili daha fazla ayrıntıyla anahtar/değer eşlemesi yer alır:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
Yukarıdaki örnekte, get yöntemi için iki parametre bulunmaktadır:serviceName ve rolloutId. Parametreler path bölümüne veya query URL'sine gidebilir; location özelliği, istemci kitaplığının parametreyi nereye yerleştirmesi gerektiğini gösterir.
type parametre verileri (kesinlikle yazılmış diller için yararlıdır), parametrenin required olup olmadığı ve parametrenin bir enum olup olmadığı gibi parametreyi açıklayan başka birçok özellik vardır. Mülkler hakkında daha fazla bilgi için Referans Kılavuzu'nu inceleyin.
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ındaki her API parametresi için bir yönteme sahip olmaktı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. Yol veya sorgu parametrelerini içerebilir ancak dizideki her parametre gereklidir. Yukarıdaki örnekte, bir Java yöntemi imzası aşağıdaki gibi görünebilir:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);parameterOrder dizisindeki ilk değer olan serviceName, yöntem imzasındaki ilk öğedir. parameterOrder dizisinde başka parametreler varsa bunlar serviceName parametresinden sonra gelir. parameterOrder dizisi yalnızca gerekli parametreleri içerdiğinden, kullanıcıların isteğe bağlı parametreleri belirtmesinin bir yöntemini eklemek de iyi bir uygulamadır. Yukarıdaki örnekte, optionalParameters eşlemesi gösterilmektedir.
Medya yükleme
Resim, ses veya video gibi medya yöntemlerinin yüklenmesi destekleniyorsa bu medyanın yüklenmesi için desteklenen konum ve protokoller mediaUpload bölümünde açıklanmıştır. Bu bölümde, desteklenen yükleme protokollerinin ayrıntıları ve ne tür medyaların yüklenebileceği hakkında bilgiler sunulmaktadır:
"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 boole değeridir. Değer doğruysa mediaUpload bölümü, yüklenebilecek medya türlerini gösterir.
accept özelliği, hangi MIME türlerinin yüklenmesine izin verildiğini belirleyen medya aralıkları listesidir. Yukarıdaki örnekte gösterilen uç nokta, tüm resim biçimlerini kabul eder.
maxSize özelliği, bir yüklemenin maksimum boyutuna sahiptir. Değer MB, GB veya TB cinsinden bir dizedir. Yukarıdaki örnekte, yüklemeler maksimum 10 MB boyutuyla sınırlıdır. Bu değerin, bağımsız bir kullanıcının söz konusu API için kalan depolama alanı kotasını yansıtmadığını unutmayın. Bu nedenle, yükleme maxSize değerinden düşük olsa bile, istemci kitaplığı yetersiz alan nedeniyle başarısız olan bir yüklemeyi yönetmek için 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ğinde belirtilen uç noktaya POSTlamaktır. resumable protokolü, path URI'sinde belirtilen uç noktanın devam ettirilebilir yükleme protokolünü desteklediği anlamına gelir. multipart özelliği true ise uç nokta, çok parçalı yüklemeleri kabul eder. Bu durumda hem JSON isteği hem de medya, bağımsız bölüm/ilgili gövde içinde sarmalanıp birlikte gönderilebilir. Hem simple hem de resumable protokollerinin çok parçalı yüklemeleri desteklediğini unutmayın.
path özelliği bir URI Şablonudur ve İstek oluştur bölümünde belirtildiği şekilde, yöntemin path özelliği gibi genişletilmelidir.
Medya indirme
Bir yöntemde resim, ses veya video gibi medya indirme işlemi destekleniyorsa supportsMediaDownload parametresi şu anlama gelir:
"supportsMediaDownload": true,
Medya indirirken istek URL'sinde alt sorgu parametresini media olarak ayarlamanız gerekir.
API yönteminin useMediaDownloadService özelliği true ise yönlendirmeden kaçınmak için servicePath öncesine /download değerini ekleyin. Örneğin, servicePath ile path birleşmesi /youtube/v3/captions/{id} ise indirme yolu /download/youtube/v3/captions/{id} olur. useMediaDownloadService yanlış olsa bile /download ile medya indirme URL'si oluşturmanız önerilir.
Sık kullanılan parametreler
Üst düzey Discovery dokümanında parameters özelliği var. Bu bölüm, her yöntemin parametreler bölümüne benzer, ancak bu parametreler API'deki herhangi bir yönteme uygulanabilir.
Örneğin, Google Cloud Service Management API'nin get, ekleme veya listeleme yöntemlerinde, istek parametrelerinde bir prettyPrint parametresi bulunabilir. Bu parametre, tüm bu yöntemlere verilen yanıtı kullanıcıların okuyabileceği bir biçimde biçimlendirir. Sık kullanılan parametrelerin listesi aşağıda verilmiştir:
| Parametre | Anlamı | Notlar | Uygulanabilirlik |
|---|---|---|---|
access_token |
Geçerli kullanıcı için OAuth 2.0 jetonu. |
|
|
alt |
Yanıtın veri biçimi. |
|
|
callback |
Geri çağırma işlevi. |
| |
fields |
Yanıta dahil edilecek alanların bir alt kümesini belirten seçici. |
|
|
key |
API anahtarı. (ZORUNLU*) |
|
|
prettyPrint |
Kimlikleri ve satır sonlarını içeren yanıtı döndürür. |
|
|
quotaUser |
userIp listesine alternatif. |
|
|
userIp |
API çağrısının yapıldığı son kullanıcının IP adresi. |
|
Özellikler
API'lerin, Discovery dokümanının geri kalanı dışındaki özel özellikleri desteklediği bazı durumlar vardır. Bunlar features dizisinde toplanır. Özellikler dizisi, API tarafından desteklenen her özellik için bir dize etiketi içerir. Şu anda dataWrapper, desteklenen tek özelliktir ancak gelecekte başka özellikler de desteklenebilir.
"features": dataWrapper
dataWrapper özelliği, API'ye yapılan tüm isteklerin ve API'den gelen yanıtların bir data JSON nesnesiyle sarmalandığını gösterir. Bu, eski Google API'lerinin bir özelliği olsa da gelecekte kullanımdan kaldırılacaktır. Şu API'ler dataWrapper özelliğini destekler: Moderatör v1 ve Çeviri v2.
İstemci kitaplığı geliştiricisi olarak bir API "dataWrapper" özelliğini destekliyorsa aşağıdakileri yapmanız gerekir:
- İsteklerde: İstek kaynağını bir
dataJSON nesnesinde sarmalayın. - Yanıtlarda:
dataJSON nesnesi içindeki kaynağı bulun.
Discovery dokümanındaki şemalarda veri sarmalayıcı yer almadığından, bunları açıkça eklemeniz ve kaldırmanız gerekir. Örneğin, "Pano" adlı bir kaynağa sahip olan bir API'nin mevcut olduğunu varsayalım:
{
"id": 1,
"foo": "bar"
}
Bu kaynağı API kullanarak eklemeden önce bir veri öğesine sarmalamanız gerekir:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Öte yandan, API'den yanıt aldığınızda veri paketi de içerir:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Şemanın tanımladığı kaynağı almak için veri sarmalayıcıyı kaldırmanız gerekir:
{
"id": 1,
"foo": "bar"
}
Satır içi dokümanlar
Her Discovery dokümanında, API için satır içi dokümanlar sağlayan çeşitli description alanları ek açıklaması bulunur. description alanları, aşağıdaki API öğeleri için bulunabilir:
- API'nin kendisi
- OAuth kapsamları
- Kaynak şemaları
- API Yöntemleri
- Yöntem parametreleri
- Belirli parametreler için kabul edilebilir değerler
Bu alanlar özellikle Java İstemcisi gibi bir istemci kitaplığı için kullanıcılar tarafından okunabilir dokümanlar oluşturmak üzere Google API Discovery Hizmeti'ni kullanmak istediğinizde kullanışlıdır.