Tworzenie biblioteki klienta

Usługi Discovery API Google możesz używać do tworzenia różnych narzędzi do korzystania z interfejsów API Google. Głównym celem dokumentu Discovery jest jednak umożliwienie Google tworzenia bibliotek klienta w różnych językach programowania. W tym dokumencie opisujemy, jak utworzyć niestandardową bibliotekę klienta interfejsów API Google.

Stabilna i w pełni funkcjonalna biblioteka klienta to złożone narzędzie, którego opracowanie może zająć wiele miesięcy. Ogólne instrukcje tworzenia prostej biblioteki klienta interfejsów API Google można jednak podzielić na 3 proste kroki:

1. Pobieranie dokumentu Discovery i tworzenie interfejsu API
2. Tworzenie prośby
3. Wykonywanie połączenia i pobieranie odpowiedzi

Szczegółowe informacje o tych krokach znajdziesz w kolejnych sekcjach. Możesz też zapoznać się z przykładowym klientem Simple APIs w sekcji Przykłady, aby zobaczyć, jak te instrukcje są odwzorowywane w kodzie.

Pobieranie dokumentu opisującego

Zanim zaczniesz wdrażać bibliotekę klienta, musisz spełnić kilka podstawowych wymagań, które wpłyną na dalszy proces rozwoju. Na przykład wybrany język programowania może być typowany lub nietypowany. Jeśli jest typowany, może być typowany statycznie lub dynamicznie. Może być skompilowany lub interpretowany. Te wymagania pomogą Ci w korzystaniu z dokumentu Discovery.

Pierwszym zadaniem programistycznym jest pobranie dokumentu Discovery. Twoja strategia dotycząca tego, kiedy dokładnie ma zostać pobrany dokument, zależy od zidentyfikowanych przez Ciebie wymagań. Na przykład w języku o statycznym typowaniu możesz pobrać dokument Discovery na wczesnym etapie procesu, a następnie wygenerować kod do obsługi konkretnego interfejsu API opisanego w tym dokumencie. W przypadku języka o silnym typowaniu możesz wygenerować kod i utworzyć skompilowaną bibliotekę. W przypadku języka o dynamicznym typowaniu możesz leniwie tworzyć struktury programowania, aby na bieżąco łączyć się z interfejsem API w miarę korzystania z platformy programowania.

Tworzenie prośby

Tworzenie żądań obejmuje 2 osobne etapy:

1. Tworzenie treści żądania.
2. Tworzenie adresu URL żądania.

Treść żądania (jeśli występuje) musisz przekonwertować z odpowiedniej dla danego języka reprezentacji na prawidłowy format transmisji. Na przykład w bibliotece klienta Java API może istnieć klasa dla każdego typu żądania, która umożliwia bezpieczną pod względem typów manipulację danymi żądania i może być serializowana do formatu JSON.

Konstruowanie adresu URL żądania jest nieco bardziej skomplikowane.

Właściwość path każdej metody w interfejsie API korzysta ze składni szablonu URI w wersji 04. Ta właściwość może zawierać zmienne ujęte w nawiasy klamrowe. Oto przykład właściwości path ze zmiennymi:

/example/path/var

W ścieżce powyżej var to zmienna. Wartość tej zmiennej pochodzi z sekcji parameters w dokumencie Discovery dla tej metody. Każda nazwa zmiennej ma odpowiednią wartość w obiekcie parameters. W przykładzie powyżej w sekcji parameters znajduje się parametr o nazwie var (a jego właściwość location ma wartość path, co oznacza, że jest to zmienna ścieżki).

Podczas wysyłania żądania zastąp w adresie URL wartość var. Jeśli na przykład użytkownik biblioteki dokona wyboru, który ustawi wartość parametru var na foo, nowy adres URL będzie wyglądać tak: /example/path/foo.

Pamiętaj też, że właściwość path to względny identyfikator URI. Aby obliczyć bezwzględny URI, wykonaj te czynności:

1. Jeśli znasz swoją lokalizację (region), a dokument Discovery zawiera właściwość endpoints, sprawdź, czy Twoja lokalizacja znajduje się na liście endpoints. Jeśli tak, wybierz endpointUrl z listy endpoints, którego location pasuje do Twojego.

2. Jeśli w dokumencie Discovery nie ma usługi endpoints lub Twoja lokalizacja nie występuje na liście endpoints albo chcesz kierować reklamy na globalny punkt końcowy, pobierz usługę rootUrl z najwyższego poziomu dokumentu Discovery.

   Na przykład właściwość rootUrl w  dokumencie Discovery dla interfejsu Service Usage API to:

   https://serviceusage.googleapis.com/

3. Pobierz wartość servicePath z najwyższego poziomu dokumentu Discovery. Na przykład właściwość servicePath w dokumencie Discovery interfejsu Service Usage API jest pusta.

4. Połącz je, aby uzyskać:

   https://serviceusage.googleapis.com/

5. Pobierz właściwość path, rozwiń ją jako szablon URI i połącz wyniki tego rozwinięcia z identyfikatorem URI z poprzedniego kroku. Na przykład w metodzie serviceusage.services.enable interfejsu Service Usage API w wersji 1 wartość właściwości path to v1/{+name}:enable. Pełny identyfikator URI metody to:

   https://serviceusage.googleapis.com/v1/{+name}:enable

Do wywoływania interfejsu Service Usage API nie jest potrzebny klucz interfejsu API. Jeśli jednak wywoływany interfejs API wymaga klucza interfejsu API, możesz dodać go do ciągu zapytania URI:

REQUEST_URI?key=API_KEY

Wykonywanie połączeń i obsługa odpowiedzi

Po wysłaniu żądania musisz zdeserializować odpowiedź do odpowiedniej reprezentacji w języku, pamiętając o obsłudze warunków błędów, które mogą wystąpić zarówno w bazowym transporcie HTTP, jak i w komunikatach o błędach generowanych przez usługę API. Format błędów jest opisany w przewodniku po stylu JSON Google.

Przykłady

W następnej sekcji znajdziesz prosty przykład biblioteki klienta interfejsów API.

Klient Simple APIs

Poniżej znajdziesz przykład bardzo prostej biblioteki klienta napisanej w Pythonie 3. Klient tworzy interfejs do interakcji z Service Usage API, a następnie używa tego interfejsu, aby włączyć Compute Engine API (compute.googleapis.com) w projekcie my-project.

Ostrzeżenie: poniższy kod to znacznie uproszczona wersja typowej biblioteki klienta. Jest to niepełna implementacja, która ma na celu zademonstrowanie niektórych aspektów tworzenia biblioteki klienta. Nie jest to kod gotowy do wdrożenia w środowisku produkcyjnym.

import httplib2
import json
import uritemplate
import urllib

# Step 1: Fetch Discovery document
DISCOVERY_URI = "https://serviceusage.googleapis.com/$discovery/rest?version=v1"
h = httplib2.Http()
resp, content = h.request(DISCOVERY_URI)
discovery = json.loads(content)
location = None # Set this to your location if appropriate
use_global_endpoint = True # Set this to False if you want to target the endpoint for your location

# Step 2.a: Construct base URI
BASE_URL = None
if not use_global_endpoint and location:
  if discovery['endpoints']:
    BASE_URL = next((item['endpointUrl'] for item in discovery['endpoints'] if item['location'] == location), None)
if not BASE_URL:
  BASE_URL = discovery['rootUrl']
BASE_URL += 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 (serviceusage.services.enable(name='projects/my-project/services/compute.googleapis.com'))

Kluczowe komponenty klienta to:

• Krok 1. Pobierz dokument Discovery Dokument Discovery interfejsu Service Usage API jest pobierany i parsowany do struktury danych. Python to język o dynamicznym typowaniu, więc dokument Discovery można pobrać w czasie działania programu.
• Krok 2a.Skonstruuj podstawowy identyfikator URI. Obliczany jest podstawowy identyfikator URI.
• Krok 2.b. Utwórz prośbę. Gdy metoda jest wywoływana w kolekcji, szablon URI jest rozwijany z parametrami przekazanymi do metody, a parametry z lokalizacją query są umieszczane w parametrach zapytania adresu URL. Na koniec żądanie jest wysyłane na utworzony adres URL za pomocą metody HTTP określonej w dokumencie Discovery.
• Krok 3a.Utwórz interfejs klienta. Interfejs klienta jest tworzony przez rekursywne przechodzenie przez przeanalizowany dokument Discovery. Dla każdej metody w sekcji methods do obiektu Collection dołączana jest nowa metoda. Kolekcje mogą być zagnieżdżone, dlatego szukamy elementu resources i rekurencyjnie tworzymy obiekt Collection dla wszystkich jego elementów, jeśli taki element zostanie znaleziony. Każda zagnieżdżona kolekcja jest też dołączana jako atrybut do obiektu Collection.
• Krok 3b. Użyj klienta Pokazuje, jak używana jest wbudowana powierzchnia interfejsu API. Najpierw obiekt usługi jest tworzony na podstawie dokumentu Discovery, a potem interfejs Service Usage API jest używany do włączenia interfejsu Compute Engine API w projekcie my-project.