Wstęp
Możesz korzystać z usługi Google APIs Discovery, aby tworzyć różne narzędzia do wykorzystania z interfejsami API Google. Głównym celem dokumentu Discovery jest jednak umożliwienie Google tworzenia bibliotek klienta w różnych językach programowania. Ta sekcja zawiera informacje o tym, jak utworzyć niestandardową bibliotekę klienta dla interfejsów API Google.
Stabilna i pełna funkcje biblioteki klienta to złożone narzędzie, którego opracowanie może zająć nawet kilka miesięcy. Ogólne instrukcje tworzenia prostej biblioteki klienta dla interfejsów API Google można podzielić na 3 proste kroki:
- Pobieranie dokumentu Discovery i tworzenie struktury interfejsu API
- Tworzenie prośby
- Wykonywanie połączenia i pobieranie odpowiedzi
Szczegółowo opisujemy to w poniższych sekcjach. Możesz też spojrzeć na przykład klienta prostych interfejsów API w sekcji Przykłady, aby zobaczyć, jak te instrukcje są mapowane na kod.
Krok 1. Pobierz dokument Discovery
Zanim zaczniesz wdrażać bibliotekę klienta, musisz spełnić kilka podstawowych wymagań, które będą miały wpływ na przebieg procesu programowania. Na przykład może to być wpisany lub nieobsługiwany język programowania. Może być skompilowany lub interpretowany. Dzięki tym wymogom poznasz sposób korzystania z dokumentu Discovery i korzystania z niego.
Pierwszym zadaniem będzie pobranie dokumentu Discovery. Strategia dotycząca dokładnego czasu pobierania dokumentu zależy od zidentyfikowanych przez Ciebie wymagań. Na przykład w języku statycznym możesz pobrać dokument Discovery na początku procesu, a potem wygenerować kod do obsługi określonego interfejsu API opisanego w dokumencie Discovery. W przypadku mocno wpisanego języka możesz wygenerować kod i skompilować bibliotekę. W przypadku języka dynamicznego stosuj leniwą konstrukcję, aby łatwo komunikować się z interfejsem API w miarę korzystania z platformy programowania.
Krok 2: Utwórz żądanie
Tworzenie prośby obejmuje 2 osobne kroki:
- Tworzenie treści żądania.
- Tworzenie adresu URL żądania.
Jeśli chcesz, musisz przekonwertować treść żądania z odpowiedniej wersji językowej na prawidłowy format przewodu (jeśli występuje). Na przykład w bibliotece klienta w języku Java może znajdować się klasa dla każdego typu żądania, która umożliwia manipulowanie danymi żądania w sposób bezpieczny i jest serializowana do JSON.
Tworzenie adresu URL żądania jest nieco bardziej skomplikowane.
Właściwość path każdej metody w interfejsie API używa składni szablonu URI v04. Ta właściwość może zawierać zmienne otoczone nawiasami klamrowymi. Oto przykład właściwości path ze zmiennymi:
/example/path/var
W powyższej ścieżce var jest zmienną. Wartość tej zmiennej pochodzi z sekcji parameters dokumentu Discovery dla tej metody. Każda nazwa zmiennej ma odpowiadającą wartość w obiekcie parameters. W powyższym przykładzie występuje parametr o nazwie var w sekcji parameters (a jego właściwość location to path, co wskazuje, że jest to zmienna ścieżki).
Podczas przesyłania żądania zastąp wartość var w adresie URL. Jeśli na przykład użytkownik biblioteki wybierze ustawienie var dla wartości foo, nowy adres URL będzie wyglądać tak: /example/path/foo.
Właściwość path jest też względnym identyfikatorem URI. Aby obliczyć bezwzględny identyfikator URI, wykonaj te czynności:
Pobierz właściwość
rootUrlz najwyższego poziomu dokumentu Discovery.
Na przykład właściwośćrootUrlw dokumencie Discovery dotyczącym interfejsu Google Cloud Service Management API to:https://servicemanagement.googleapis.com/Ustaw
servicePathna najwyższym poziomie dokumentu Discovery.
Na przykład właściwośćservicePathw dokumencie Discovery dla interfejsu API zarządzania usługami Google Cloud jest pusta.Połącz je, aby:
https://servicemanagement.googleapis.com/Chwyć właściwość
path, rozwiń ją jako szablon URI i połącz wyniki tego rozszerzenia z identyfikatorem URI z poprzedniego kroku.
Na przykład w interfejsie API usługi Google Cloud Service Managementgetwartość właściwościpathtov1/services/{serviceName}. Pełny identyfikator URI tej metody to:https://servicemanagement.googleapis.com/v1/services/{serviceName}
Aby wywołać interfejs Google Cloud Service Management API, musisz mieć klucz interfejsu API. Po zastosowaniu klucza interfejsu API pełny identyfikator URI pobierany w celu zdefiniowania usługi usługi wykrywania interfejsu API wygląda tak:
https://servicemanagement.googleapis.com/v1/services/discovery.googleapis.com?key=API_KEY
Krok 3. Zadzwoń i odpowiedz
Po wysłaniu żądania musisz zwięźle odpowiedzieć na właściwą reprezentację języka, uwzględniając błędy, które mogą wystąpić, zarówno w transporcie podstawowym HTTP, jak i komunikaty o błędach generowane przez usługę API. Format błędów jest opisany w Przewodniku po stylu Google JSON.
Przykłady
Typowe przykłady bibliotek i narzędzi klienta, które zostały wdrożone za pomocą usługi wykrywania interfejsów API Google, znajdziesz w dokumencie Biblioteki i próbki. Poniżej znajdziesz też przykładową bibliotekę klienta API.
Prosty klient API
Poniżej znajduje się przykład bardzo prostej biblioteki klienta napisanej w języku Python3 . Klient tworzy interfejs do interakcji z interfejsem Google Cloud Service Management API, a następnie otrzymuje definicję usługi wykrywania usług za pomocą tego interfejsu.
Ostrzeżenie: poniższy kod jest znacznie uproszczoną wersją typowej biblioteki klienta. To niekompletna implementacja, która ma na celu zaprezentowanie niektórych aspektów tworzenia biblioteki klienta. Nie jest to kod gotowy do produkcji.
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'))
Główne komponenty klienta to:
- Krok 1. Pobierz dokument Discovery.
Dokument Discovery interfejsu API Google Cloud Service Management API jest pobierany i analizowane w strukturze danych. Python jest językiem wpisanym dynamicznie, dlatego dokument Discovery można pobrać w czasie działania. - Krok 2.a. Utwórz podstawowy identyfikator URI.
Podstawowy identyfikator URI jest obliczany. - Krok 2.b: utwórz żądanie
Po wywołaniu metody w kolekcji szablon URI zostanie rozwinięty z parametrami przekazanymi do metody, a parametry z lokalizacjąquery– w parametrach zapytania adresu URL. Na koniec żądanie jest wysyłane do skomponowanego adresu URL przy użyciu metody HTTP określonej w dokumencie Discovery. - Krok 3.a: utwórz platformę klienta
Platformę klienta tworzy się malejąco nad analizowanym dokumentem Discovery. Do każdej metody w sekcjimethodsdo obiektuCollectionjest przypisana nowa metoda. Ponieważ kolekcje mogą być zagnieżdżone, szukamy obiekturesourcesi rekurencyjnie tworzymy obiektCollectiondla wszystkich jej członków, jeśli go znajdzie. Każda zagnieżdżona kolekcja jest też dołączana jako atrybut do obiektuCollection. - Krok 3.b. Użyj klienta.
Ten przykład pokazuje, jak używana jest utworzona interfejs API. Najpierw obiekt usługi jest tworzony na podstawie dokumentu Discovery, a następnie definicja usługi usługi wykrywania interfejsu API jest pobierana przez interfejs Google Cloud Service Management API.