Bu sayfa, Cloud Translation API ile çevrilmiştir.

İstemci kitaplığı oluşturma

Giriş

Google API'leri ile kullanmak üzere çeşitli araçlar oluşturmak için Google API Discovery Hizmeti'ni kullanabilirsiniz. Ancak Discovery dokümanının birincil amacı, Google'ın çeşitli programlama dillerinde istemci kitaplıkları oluşturmasına izin vermektir. Bu bölümde, Google API'leri için özel istemci kitaplığı oluşturmaya nasıl başlayabileceğiniz açıklanmaktadır.

Kararlı ve eksiksiz bir istemci kitaplığı, geliştirilmesi aylar sürebilen karmaşık bir araçtır. Ancak, Google API'leri için basit bir istemci kitaplığı oluşturmaya ilişkin genel talimatlar üç basit adıma ayrılabilir:

Discovery dokümanını getirme ve API yüzeyini oluşturma
İstek oluşturma
Telefon etme ve yanıtı getirme

Bu adımlar sonraki bölümlerde daha ayrıntılı olarak açıklanmıştır. Bu talimatların kodla nasıl eşleştiğini görmek için Örnekler bölümündeki Basit API'ler istemcisi örneğine de bakabilirsiniz.

1. Adım: Discovery dokümanını getirin

İstemci kitaplığı uygulamaya başlamadan önce, geliştirme yolculuğunuzda nasıl ilerleyeceğinizi etkileyen bazı temel şartlar bulunur. Örneğin, tercih ettiğiniz programlama dili yazılabilir veya yazılmamış olabilir. Yazılırsa statik veya dinamik olarak yazılabilir. Bu derleme derlenebilir veya yorumlanabilir. Bu gereksinimler, Discovery dokümanını kullanma ve kullanma yaklaşımınızı şekillendirir.

İlk geliştirme görevi Discovery dokümanını getirmektir. Belgenin tam olarak ne zaman getirileceğine dair stratejiniz, belirlediğiniz şartlara göre belirlenir. Örneğin, statik olarak yazılan bir dilde, Discovery dokümanını sürecin başlarında getirebilir, ardından Discovery dokümanı tarafından açıklanan belirli bir API'yi işlemek için kod oluşturabilirsiniz. Çok sık yazılan bir dil için kod oluşturup derlenmiş bir kitaplık oluşturabilirsiniz. Dinamik olarak yazılan bir dil için, programlama yüzeyi kullanılırken, API'yi hızlı bir şekilde arayüzle temsil edecek şekilde programlama yapıları oluşturabilirsiniz.

2. Adım: Bir istek oluşturun

İstek oluşturmanın iki ayrı adımı vardır:

İstek gövdesini oluşturmak.
İstek URL'sini oluşturma.

İstek gövdesini, varsa dile uygun bir temsilden doğru kablo biçimine dönüştürmeniz gerekir. Örneğin, bir Java istemci kitaplığında, her bir istek türü için istek verilerinin sorunsuz olarak işlenmesine olanak tanıyan ve JSON'da serileştirilebilen bir sınıf olabilir.

İstek URL'sinin oluşturulması biraz daha karmaşık bir işlemdir.

API'deki her yöntemin path özelliği URI Şablon v04 söz dizimini kullanır. Bu özellik, süslü ayraçlarla çevrili değişkenler içerebilir. Değişkenleri içeren bir path özelliği örneğini burada bulabilirsiniz:

/example/path/var

Yukarıdaki yolda var bir değişkendir. Bu değişkenin değeri, söz konusu yöntem için Discovery dokümanının parameters bölümünden gelir. Her değişken adının parameters nesnesinde karşılık gelen bir değeri vardır. Yukarıdaki örnekte, parameters bölümünde var adında bir parametre vardır (ve bunun bir değişken olduğunu belirtmek için location özelliği path'dir).

İstekte bulunurken URL'yi var değeriyle değiştirmeniz gerekir. Örneğin, kitaplık kullanıcısı var değerini foo değerine ayarlayan bir seçenek belirlerse yeni URL /example/path/foo olur.

Ayrıca, path özelliğinin göreli bir URI olduğunu unutmayın. Mutlak URI'yi hesaplamak için şu adımları uygulayın:

Keşif dokümanının en üst düzeyindeki rootUrl özelliğini kullanın.
Örneğin, Google Cloud Service Management API için Discovery dokümanındaki rootUrl özelliği:

https://servicemanagement.googleapis.com/
Keşif dokümanının en üst kısmından servicePath edinin.
Örneğin, Google Cloud Service Management API için Discovery dokümanındaki servicePath özelliği boş.
Aşağıdakileri elde etmek için bunları birleştirin:

https://servicemanagement.googleapis.com/
path özelliğini alın, URI Şablonu olarak genişletin ve bu genişletmenin sonuçlarını önceki adımın URI'siyle birleştirin.
Örneğin, Google Cloud Service Management API&#39'nın get hizmet yönteminde path özelliğinin değeri v1/services/{serviceName} olur. Bu durumda, yöntemin tam URI'si şudur:

https://servicemanagement.googleapis.com/v1/services/{serviceName}

Google Cloud Service Management API'yi çağırmak için bir API anahtarı gereklidir. Böylece, bir API anahtarı uygulandıktan sonra API Discovery Hizmeti'nin hizmet tanımını almak için tam URI şöyle olur:

https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY

3. Adım: Arama yapın ve yanıtı yönetin

İsteği gönderdikten sonra, yanıtı uygun dil temsiline serileştirmeniz gerekir. Bu işlem, hem temel HTTP aktarımında hem de API hizmetinden oluşturulan hata mesajlarında ortaya çıkabilecek hata durumlarıyla başa çıkmaya özen gösterir. Hataların biçimi Google JSON Stil Kılavuzu'nun bir parçası olarak açıklanmıştır.

Örnekler

Google API Discovery Hizmeti kullanılarak uygulanan istemci kitaplıklarının ve araçların somut örnekleri için Kitaplıklar ve Örnekler dokümanını inceleyin. Ayrıca aşağıdaki bölümde bir API istemci kitaplığı basit bir örneği verilmiştir.

Basit API'ler istemcisi

Aşağıda, Python3'te yazılmış çok basit bir istemci kitaplığı örneği verilmiştir . İstemci, Google Cloud Service Management API ile etkileşimde bulunmak için bir arayüz oluşturur ve daha sonra bu arayüzü kullanarak API Discovery Hizmeti'nin hizmet tanımını alır.

Uyarı: Aşağıdaki kod, tipik bir istemci kitaplığının önemli ölçüde basitleştirilmiş bir sürümüdür. İstemci kitaplığı oluşturmanın bazı yönlerini göstermek için sağlanan eksik bir uygulamadır. Bu, üretime hazır bir kod değildir.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://servicemanagement.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)

# Step 2.a: Construct base URI
BASE_URL = discovery['rootUrl'] + 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 (service.services.get(serviceName='discovery.googleapis.com', key='API_KEY'))

İstemcinin temel bileşenleri şunlardır:

1. Adım: Keşif dokümanını getirin.
Google Cloud Service Management API'nin Discovery dokümanı alınır ve veri yapısına ayrıştırılır. Python dinamik olarak yazılan bir dil olduğundan, Discovery dokümanı çalışma zamanında getirilebilir.
2.a Adımı: Temel URI'yi oluşturun.
Temel URI hesaplanır.
2.b Adımı: İsteği oluşturun.
Koleksiyonda bir yöntem çağrıldığında, URI Şablonu yönteme aktarılan parametrelerle genişletilir ve query konuma sahip parametreler, URL'nin sorgu parametrelerine yerleştirilir. Son olarak, Discovery dokümanında belirtilen HTTP yöntemi kullanılarak, oluşturulan URL'ye bir istek gönderilir.
3.a adımı: İstemci yüzeyini oluşturun.
İstemci yüzeyi, ayrıştırılan Keşif dokümanı üzerinde yinelenen bir şekilde azalan şekilde oluşturulur. methods bölümündeki her yöntem için Collection nesnesine yeni bir yöntem eklenir. Koleksiyonlar iç içe yerleştirilebildiğinden, resources aranır ve bulunması halinde tüm üyeleri için yinelenen bir Collection nesnesi oluştururuz. İç içe yerleştirilmiş her koleksiyon, Collection nesnesine de özellik olarak eklenir.
3.b adımı: İstemciyi kullanın.
Bu, yerleşik API yüzeyinin nasıl kullanıldığını gösterir. Önce Discovery dokümanından bir hizmet nesnesi oluşturulur, ardından API Discovery Hizmeti'nin hizmet tanımı Google Cloud Service Management API aracılığıyla alınır.