Wstęp
Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć biblioteki klienta, wtyczki IDE i inne narzędzia do korzystania z interfejsów API Google. Usługa wykrywania interfejsów API Google umożliwia wykonanie wszystkich tych czynności przez udostępnienie metadanych czytelnych dla komputera za pomocą innych interfejsów API Google. W tym przewodniku znajdziesz omówienie każdej sekcji dokumentu Discovery oraz przydatne wskazówki na temat korzystania z niego.
Wszystkie wywołania interfejsu API są nieuwierzytelnione za pomocą żądań JSON i REST przy użyciu protokołu SSL. Oznacza to, że adresy URL zaczynają się od https.
Jeśli nie znasz pojęć związanych z usługą Google Discovery, zapoznaj się z artykułem Pierwsze kroki.
Format dokumentu opisującego
Ta sekcja zawiera omówienie dokumentu wykrywania.
Wszystkie przykłady poniżej korzystają z dokumentu wykrywania z interfejsu Google Cloud Service Management API. Dokument Discovery dla interfejsu Google Cloud Service Management API możesz wczytać, wykonując to żądanie GET:
GET https://servicemanagement.googleapis.com/$discovery/rest?version=v1Format dokumentu wykrywania zawiera informacje, które można podzielić na 6 głównych kategorii:
- Podstawowy opis interfejsu API.
- Informacje o uwierzytelnianiu interfejsu API.
- Szczegóły zasobu i schematu opisujące dane interfejsu API.
- Szczegółowe informacje o metodach interfejsu API.
- Informacje o niestandardowych funkcjach obsługiwanych przez interfejs API.
- Wbudowana dokumentacja opisująca najważniejsze elementy interfejsu API.
Poniżej opisano każdą z tych sekcji dokumentu opisującego. Więcej informacji o poszczególnych usługach znajdziesz w dokumentacji.
Podstawowy opis interfejsu API
Dokument Discovery zawiera zestaw właściwości charakterystycznych dla interfejsu API:
"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": "",
Te właściwości na poziomie interfejsu API obejmują szczegóły konkretnej wersji interfejsu API, w tym name, version, title i description. protocol ma zawsze stałą wartość rest, ponieważ usługa wykrywania interfejsów API obsługuje tylko metody dostępu do interfejsów API typu REST.
Pole servicePath wskazuje prefiks ścieżki do tej konkretnej wersji interfejsu API.
Uwierzytelnianie
Sekcja auth zawiera szczegółowe informacje o zakresach uwierzytelniania OAuth 2.0 dla interfejsu API. Więcej informacji o korzystaniu z zakresów z OAuth 2.0 znajdziesz w artykule Korzystanie z OAuth 2.0 do korzystania z interfejsów API Google.
Sekcja auth zawiera zagnieżdżone sekcje oauth2 i scopes. Sekcja scopes mapuje klucz/wartość z wartości zakresu na bardziej szczegółowe informacje o zakresie:
"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"
}
}
}
}
Sekcja auth definiuje tylko zakresy dla określonego interfejsu API. Aby dowiedzieć się, jak te zakresy są powiązane z metodą interfejsu API, zajrzyj do sekcji Metody poniżej.
Zasoby i schematy
Operacje API wykonywane na obiektach danych o nazwie resources. Dokument Discovery bazuje na koncepcji zasobów. Każdy dokument Discovery zawiera sekcję resources najwyższego poziomu, która grupuje wszystkie zasoby powiązane z interfejsem API. Na przykład interfejs Google Cloud Service Management API ma jeden zasób (services) i operations (zasób typu operations) najwyższego poziomu, zasób services ma 3 zasoby podrzędne: configs, rollouts i consumers:
"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
}
}
W każdej sekcji zasobu znajdują się powiązane z nim metody. Na przykład interfejs Google Cloud Service Management API ma trzy metody powiązane z zasobem services.rollouts: get, list i create.
Schematy określają wygląd zasobów w interfejsie API. Każdy dokument Discovery ma sekcję schemas najwyższego poziomu, która zawiera parę nazwy/wartości identyfikatora schematu do obiektu. Identyfikatory schematów są unikalne dla interfejsu API i służą do jednoznacznej identyfikacji schematu w sekcji methods dokumentu Discovery:
"schemas": {
"Rollout": {
// JSON Schema of the Rollout resource.
}
}
Usługa wykrywania interfejsów API używa do reprezentowania schematu schematu JSON JSON-03. Oto fragment kodu JSON dla zasobu adresu URL wraz z rzeczywistym zasobem odpowiedzi:
| Schemat JSON zasobu wdrożenia: | rzeczywista odpowiedź zasobu: |
{
"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
}
}
}
|
Pogrubione pola pokazują mapowanie między schematem JSON a faktyczną odpowiedzią.
Schematy mogą też zawierać odwołania do innych schematów. Jeśli tworzysz bibliotekę klienta, możesz skutecznie modelować obiekty interfejsu API w klasach modeli danych. W przykładzie powyżej Rollout właściwość trafficPercentStrategy jest w rzeczywistości odniesieniem do schematu o identyfikatorze TrafficPercentStrategy. W sekcji schemas znajdziesz schemat TrafficPercentStrategy. Wartość tego schematu można zastąpić właściwością trafficPercentStrategy w zasobie Rollout (pamiętaj, że składnia $ref pochodzi ze specyfikacji schematu JSON).
Metody mogą też odwoływać się do schematów podczas wskazywania treści żądań i odpowiedzi. Więcej informacji znajdziesz w sekcji Metody.
Metody
Podstawą dokumentu opisującego są metody. Metody to operacje, które można przeprowadzić za pomocą interfejsu API. Sekcja methods znajduje się w różnych obszarach dokumentu Discovery, w tym na najwyższym poziomie (metody nazywane metodami interfejsu API) lub na poziomie resources.
"methods": {
// API-level methods
}
"resources": {
"resource1": {
"methods": {
// resource-level methods
}
"resources": {
"nestedResource": {
"methods": {
// methods can even be found in nested-resources
}
}
}
}
}
Interfejs API może mieć metody na poziomie interfejsu API, ale zasób musi mieć sekcję methods.
Każda sekcja methods to mapa klucz/wartość, od nazwy metody do innych szczegółów. W przykładzie poniżej widać 3 metody: get, list i create:
"methods": {
"get": { //details about the "get" method },
"list": { //details about the "list" method },
"create": { //details about the "create" method }
}
Każda sekcja metody zawiera informacje o jej właściwościach. Oto przykład metody get:
"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 },
},
Ta sekcja zawiera ogólne informacje o metodzie, takie jak unikalny identyfikator ID służący do identyfikacji metody, httpMethod używane oraz path metody (szczegóły na temat sposobu obliczania pełnego adresu URL metody za pomocą właściwości path znajdziesz w sekcji Tworzenie żądania). Oprócz tych ogólnych właściwości metody istnieje kilka właściwości, które łączą tę metodę z innymi sekcjami w dokumencie Discovery:
Zakresy
Sekcja auth opisana wcześniej w tej dokumentacji zawiera informacje na temat wszystkich zakresów obsługiwanych przez konkretny interfejs API. Jeśli metoda obsługuje jeden z tych zakresów, będzie mieć tablicę zakresów. Ta tablica zawiera jeden wpis na każdy zakres obsługiwany przez tę metodę. Na przykład sekcja scopes metody interfejsu Google Cloud Service Management API get wygląda tak:
"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" ]
Pamiętaj, że zakres uwierzytelniania używany w aplikacji zależy od różnych czynników, np. wywoływanych metod i parametrów wysyłanych wraz z metodą. W związku z tym to deweloper decyduje, którego zakresu użyć. Discovery pokazuje tylko te zakresy, które są prawidłowe w przypadku danej metody.
Prośba i odpowiedź
Jeśli metoda zawiera treść żądania lub odpowiedzi, są one odpowiednio udokumentowane w sekcjach request i response. W powyższym przykładzie get metoda zawiera treść response:
"response": {
"$ref": "Rollout"
}
Powyższa składnia wskazuje, że treść odpowiedzi jest zdefiniowana w schemacie JSON o identyfikatorze Rollout. Schemat znajdziesz w sekcji Schematy najwyższego poziomu. Zarówno żądania, jak i treści odpowiedzi używają składni $ref do odwoływania się do schematów.
Parametry
Jeśli metoda powinna zawierać parametry, które musi określić użytkownik, parametry te znajdziesz w sekcji parameters na poziomie metody. Ta sekcja zawiera mapowanie par klucz-wartość nazwy parametru, by dowiedzieć się więcej o tym parametrze:
"parameters": {
"serviceName": {
"type": "string",
"description": "Required. The name of the service.",
"required": true,
"location": "path"
},
"rolloutId": { ... }
},
"parameterOrder": [
"serviceName",
"rolloutId"
]
W powyższym przykładzie są 2 parametry metody get: serviceName i rolloutId. Parametry mogą znajdować się w tagu path lub w adresie URL query. Właściwość location wskazuje, gdzie biblioteka klienta powinna umieścić parametr.
Jest wiele innych właściwości opisujących ten parametr, w tym dane parametru type (przydatne w przypadku języków o dużym typie), required (a także to, czy parametr jest wyliczeniem). Więcej informacji o właściwościach znajdziesz w przewodniku.
Kolejność parametrów
Jest wiele sposobów na uporządkowanie interfejsów w bibliotekach klienta. Jednym ze sposobów jest podanie metody wraz z każdym parametrem interfejsu API w podpisie metody. Ponieważ format JSON jest nieuporządkowany, trudno jest automatycznie określić parametry w podpisie metody. Tablica parameterOrder zawiera stałą kolejność parametrów dla żądań. Tablica zawiera nazwę każdego parametru w kolejności, w której znajduje się ścieżka lub parametry zapytania, ale każdy parametr w tablicy jest wymagany. W powyższym przykładzie podpis metody Java może wyglądać mniej więcej tak:
public Rollout get(String serviceName, String rolloutId, Map<String, Object> optionalParameters);Pierwsza wartość w tablicy parameterOrder, serviceName, jest również pierwszym elementem w metodzie podpisu. Jeśli w tablicy parameterOrder występują inne parametry, zostaną one przekazane po parametrze serviceName. Tablica parameterOrder zawiera tylko wymagane parametry, dlatego warto uwzględnić sposób, w jaki użytkownicy mogą określić też parametry opcjonalne. W przykładzie powyżej pokazujemy mapę optionalParameters.
Przesyłanie multimediów
Jeśli metoda obsługuje przesyłanie multimediów, np. obrazów, plików audio lub wideo, lokalizacja i protokoły obsługiwane w przypadku przesyłania multimediów są opisane w sekcji mediaUpload. Ta sekcja zawiera szczegółowe informacje o tym, które protokoły są obsługiwane, a także o rodzajach multimediów, które można przesyłać:
"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"
}
}
}
W przykładzie powyżej właściwość supportsMediaUpload jest wartością logiczną, która określa, czy metoda obsługuje przesyłanie multimediów. Jeśli wartość to „true”, sekcja mediaUpload dokumentuje rodzaje multimediów, które można przesyłać.
Właściwość accept to lista zakresów multimediów, które określają, jakie typy MIME można przesłać. Punkt końcowy pokazany w powyższym przykładzie akceptuje dowolny format obrazu.
Maksymalny rozmiar przesyłanych danych jest właściwość maxSize. Wartość jest ciągiem znaków w MB, GB lub TB. W tym przykładzie film może mieć maksymalnie 10 MB. Ta wartość nie odzwierciedla pozostałego limitu miejsca użytkownika w tym interfejsie API, więc nawet jeśli przesyłanie jest mniejsze niż maxSize, biblioteka klienta powinna być gotowa do obsługi przesłanych plików z powodu braku miejsca.
Sekcja protocols zawiera listę protokołów przesyłania obsługiwanych przez metodę. Protokół simple po prostu przesyła nośnik do danego punktu końcowego w pojedynczym żądaniu HTTP. Protokół resumable wskazuje, że punkt końcowy określony w identyfikatorze URI path obsługuje protokół przesyłania możliwego do wznowienia. Jeśli właściwość multipart ma wartość true, punkt końcowy akceptuje przesyłanie wieloczęściowe, co oznacza, że zarówno żądanie JSON, jak i multimedia mogą być spakowane w treści wspólnej lub powiązanej i można je wysyłać razem. Pamiętaj, że protokoły simple i resumable mogą obsługiwać przesyłanie wieloczęściowe.
Właściwość path jest szablonem URI i powinna być rozwinięta tak samo jak właściwość path zgodnie z opisem w sekcji Tworzenie żądania.
Pobranie multimediów
Jeśli metoda obsługuje pobieranie multimediów, takich jak obrazy, pliki audio lub wideo, oznacza to, że parametr supportsMediaDownload:
"supportsMediaDownload": true,
Podczas pobierania multimediów musisz ustawić w adresie URL żądania parametr zapytania alt na media.
Jeśli właściwość useMediaDownloadService metody interfejsu API to true, wstaw /download przed servicePath, aby uniknąć przekierowania. Na przykład ścieżka pobierania to /download/youtube/v3/captions/{id}, jeśli kombinacja servicePath i path to /youtube/v3/captions/{id}. Zalecamy utworzenie adresu URL do pobierania multimediów z elementem /download, nawet jeśli useMediaDownloadService ma wartość Fałsz.
Typowe parametry
Dokument najwyższego poziomu zawiera właściwość parameters. Ta sekcja jest podobna do sekcji parametrów dla każdej metody, ale można je stosować do dowolnej metody w interfejsie API.
Na przykład metody pobierania, wstawiania i wyświetlania listy w interfejsie API Google Cloud Service Management mogą mieć parametr prettyPrint w parametrze żądania, który formatuje odpowiedź wszystkich tych metod w formacie czytelnym dla człowieka. Oto lista popularnych parametrów:
| Parametr | Znaczenie | Uwagi | Obowiązywanie |
|---|---|---|---|
access_token |
Token OAuth 2.0 dla bieżącego użytkownika. |
|
|
alt |
Format danych odpowiedzi. |
|
|
callback |
Funkcja wywołania zwrotnego. |
| |
fields |
Selektor określający podzbiór pól do uwzględnienia w odpowiedzi. |
|
|
key |
Klucz interfejsu API. (WYMAGANE*) |
|
|
prettyPrint |
Zwraca odpowiedź z Identyfikacją i podziałami wierszy. |
|
|
quotaUser |
Alternatywa dla: userIp. |
|
|
userIp |
Adres IP użytkownika, dla którego wykonywane jest wywołanie interfejsu API. |
|
Funkcje
W niektórych przypadkach interfejsy API obsługują funkcje niestandardowe poza zakresem pozostałych elementów dokumentu Discovery. Są one zbierane w tablicy features. Tablica funkcji zawiera etykietę ciągu dla każdej funkcji specjalnej obsługiwanej przez interfejs API. Obecnie dataWrapper to jedyna obsługiwana funkcja, ale w przyszłości mogą być obsługiwane inne funkcje.
"features": dataWrapper
Funkcja dataWrapper wskazuje, że wszystkie żądania wysyłane do interfejsu API i odpowiedzi z niego są umieszczane w obiekcie JSON data. Jest to funkcja starszych interfejsów Google API, ale jest ona wycofywana. Funkcja dataWrapper jest dostępna w tych interfejsach API: Moderator v1 i Tłumacz v2.
Jako deweloper biblioteki klienta, jeśli interfejs API obsługuje funkcję "dataWrapper", wykonaj te czynności:
- Przy żądaniach: pakuj zasób żądania w obiekcie JSON
data. - Odpowiedzi: znajdź zasób w obiekcie JSON
data.
Schematy w dokumencie Discovery nie zawierają kodu danych, więc musisz je dodać lub usunąć. Załóżmy na przykład, że istnieje interfejs API z zasobem o nazwie &"Foo", który wygląda tak:
{
"id": 1,
"foo": "bar"
}
Zanim wstawisz ten zasób za pomocą interfejsu API, musisz pakować go w elemencie danych:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Z drugiej strony odpowiedź z interfejsu API zawiera też kod danych:
{
"data": {
"id": 1,
"foo": "bar"
}
}
Aby pobrać zasób zdefiniowany w schemacie, musisz usunąć kod.
{
"id": 1,
"foo": "bar"
}
Wbudowana dokumentacja
Każdy dokument Discovery ma adnotacje z wieloma polami description, które zawierają wbudowaną dokumentację interfejsu API. Pola description można znaleźć w przypadku tych elementów interfejsu API:
- Sam interfejs API
- Zakresy OAuth
- Schematy zasobów
- Metody interfejsu API
- Parametry metody
- Akceptowane wartości niektórych parametrów
Te pola są szczególnie przydatne, gdy chcesz użyć usługi wykrywania interfejsów API Google do wygenerowania dokumentacji zrozumiałej dla człowieka dla biblioteki klienta, takiej jak JavaDoc.