Korzystanie z interfejsu Discovery API

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać biblioteki klienta, wtyczki IDE i inne narzędzia do interakcji z interfejsami API Google. Usługa Discovery interfejsów API Google umożliwia wykonanie wszystkich powyższych czynności dzięki udostępnianiu metadanych innych interfejsów API Google w formacie czytelnym dla maszyn za pomocą prostego interfejsu API. Ten przewodnik zawiera omówienie każdej sekcji dokumentu Discovery oraz przydatne wskazówki dotyczące korzystania z niego.

Wszystkie wywołania interfejsu API to nieuwierzytelnione żądania REST oparte na JSON, które korzystają z protokołu SSL, czyli adresy URL zaczynają się od https.

Format dokumentu opisującego

W tej sekcji znajdziesz ogólne informacje o dokumencie Discovery.

Wszystkie poniższe przykłady korzystają z dokumentu Discovery z interfejsu Service Usage API. Możesz wczytać dokument opisujący interfejs Service Usage API, wykonując to żądanie GET:

GET https://serviceusage.googleapis.com/$discovery/rest?version=v1

Format dokumentu opisującego zawiera informacje podzielone na 6 głównych kategorii:

• Podstawowy opis interfejsu API.
• Informacje o uwierzytelnianiu w interfejsie API.
• Szczegóły zasobu i schematu opisujące dane interfejsu API.
• Szczegółowe informacje o metodach interfejsu API.
• Informacje o wszystkich niestandardowych funkcjach obsługiwanych przez interfejs API.
• Dokumentacja wbudowana opisująca kluczowe elementy interfejsu API.

Poniżej znajdziesz opis każdej z tych sekcji dokumentu Discovery.

Podstawowy opis interfejsu API

Dokument Discovery zawiera zestaw właściwości specyficznych dla interfejsu API. Te właściwości nie muszą pojawiać się w tej kolejności ani w tej samej sekcji dokumentu z informacjami o usłudze:

"id": "serviceusage:v1",
"canonicalName": "Service Usage",
"revision": "20240331",
"servicePath": "",
"baseUrl": "https://serviceusage.googleapis.com/",
"kind": "discovery#restDescription",
"description": "Enables services that service consumers want to use on Google Cloud Platform, lists the available or enabled services, or disables services that service consumers no longer use.",
"ownerDomain": "google.com",
"version_module": true,
"version": "v1",
"fullyEncodeReservedExpansion": true,
"name": "serviceusage",
"title": "Service Usage API",
"discoveryVersion": "v1",
"rootUrl": "https://serviceusage.googleapis.com/",
"protocol": "rest"

Właściwości na poziomie interfejsu API zawierają szczegółowe informacje o konkretnej wersji interfejsu API, w tym name, version, title i description. Parametr protocol ma zawsze stałą wartość rest, ponieważ usługa wykrywania interfejsów API obsługuje tylko metody RESTful dostępu do interfejsów API.

Pole servicePath wskazuje prefiks ścieżki dla tej konkretnej wersji interfejsu API.

Uwierzytelnianie

Sekcja auth zawiera szczegółowe informacje o zakresach autoryzacji OAuth 2.0 dla interfejsu API. Więcej informacji o używaniu zakresów z OAuth 2.0 znajdziesz w artykule Używanie OAuth 2.0 do korzystania z interfejsów API Google.

Sekcja auth zawiera zagnieżdżone sekcje oauth2 i scopes. Sekcja scopes to mapowanie klucz-wartość z wartości zakresu na więcej informacji o zakresie:

"auth": {
  "oauth2": {
    "scopes": {
      "https://www.googleapis.com/auth/cloud-platform": {
        "description": "See, edit, configure, and delete your Google Cloud data and see the email address for your Google Account."
      },
      "https://www.googleapis.com/auth/cloud-platform.read-only": {
        "description": "View your data across Google Cloud services and see the email address of your Google Account"
      },
      "https://www.googleapis.com/auth/service.management": {
        "description": "Manage your Google API service configuration"
      }
    }
  }
}

Sekcja auth określa tylko zakresy dla danego interfejsu API. Aby dowiedzieć się, jak te zakresy są powiązane z metodą interfejsu API, zapoznaj się z sekcją Metody poniżej.

Zasoby i schematy

Operacje interfejsu API działają na obiektach danych zwanych resources. Dokument wykrywania jest oparty na koncepcji zasobów. Każdy dokument Discovery ma sekcję najwyższego poziomu resources, która grupuje wszystkie zasoby powiązane z interfejsem API. Na przykład interfejs Service Usage API ma zasób services i zasób operations w elemencie najwyższego poziomu resources:

"resources": {
  "services": {
    // Methods associated with the services resource
  }
  "operations": {
    // Methods associated with the operations resource
  }
}

W każdej sekcji zasobów znajdują się metody powiązane z tym zasobem. Na przykład interfejs Service Usage API ma 6 metod powiązanych z zasobem services: get, enable, disable, batchGet, batchEnable i list.

Schematy określają wygląd zasobów w interfejsie API. Każdy dokument Discovery ma sekcję najwyższego poziomu schemas, która zawiera parę nazwa/wartość identyfikatora schematu do obiektu. Identyfikatory schematu są unikalne dla każdego interfejsu API i służą do jednoznacznej identyfikacji schematu w sekcji methods dokumentu Discovery. Oto kilka przykładów schematów w dokumencie Discovery interfejsu Service Usage API:

"schemas": {
  "Method": {
    // JSON schema of the Method resource
  },
  "Authentication": {
    // JSON schema of the Authentication resource
  },
  "RubySettings": {
    // JSON schema of the RubySettings resource
  },
  "EnableServiceResponse": {
   // JSON schema of the EnableServiceResponse resource
  }
}

Usługa wykrywania interfejsów API używa do reprezentacji schematów schematu JSON w wersji draft-03. Poniżej znajduje się fragment schematu JSON zasobu EnableServiceResponse wraz z odwołującym się do niego zasobem GoogleApiServiceusagev1Service. Obok tych schematów znajduje się fragment rzeczywistej odpowiedzi na żądanie włączenia interfejsu Pub/Sub API (pubsub.googleapis.com).

"EnableServiceResponse": {
  "id": "EnableServiceResponse",
  "description": "Response message for the `EnableService` method. This response message is assigned to the `response` field of the returned Operation when that operation is done.",
  "properties": {
    "service": {
      "description": "The new state of the service after enabling.",
      "$ref": "GoogleApiServiceusageV1Service"
    }
  },
  "type": "object"
},
"GoogleApiServiceusageV1Service": {
  "description": "A service that is available for use by the consumer.",
  "properties": {
    "config": {
      "$ref": "GoogleApiServiceusageV1ServiceConfig",
      "description": "The service configuration of the available service. Some fields may be filtered out of the configuration in responses to the `ListServices` method. These fields are present only in responses to the `GetService` method."
    },
    "name": {
      "type": "string",
      "description": "The resource name of the consumer and service. A valid name would be: - projects/123/services/serviceusage.googleapis.com"
    },
    "state": {
      "enumDescriptions": [
        "The default value, which indicates that the enabled state of the service is unspecified or not meaningful. Currently, all consumers other than projects (such as folders and organizations) are always in this state.",
        "The service cannot be used by this consumer. It has either been explicitly disabled, or has never been enabled.",
        "The service has been explicitly enabled for use by this consumer."
      ],
      "description": "Whether or not the service has been enabled for use by the consumer.",
      "type": "string",
      "enum": [
        "STATE_UNSPECIFIED",
        "DISABLED",
        "ENABLED"
      ]
    },
    "parent": {
      "type": "string",
      "description": "The resource name of the consumer. A valid name would be: - projects/123"
    }
  },
  "id": "GoogleApiServiceusageV1Service",
  "type": "object"
}

"response": {
  "@type": "type.googleapis.com/google.api.serviceusage.v1.EnableServiceResponse",
  "service": {
    "name": "projects/232342569935/services/pubsub.googleapis.com",
    "config": {
      "name": "pubsub.googleapis.com",
      "title": "Cloud Pub/Sub API",
      "documentation": {
        "summary": "Provides reliable, many-to-many, asynchronous messaging between applications.\n"
      },
      "quota": {},
      "authentication": {},
      "usage": {
        "requirements": [
          "serviceusage.googleapis.com/tos/cloud"
        ]
      },
      "monitoring": {}
    },
    "state": "ENABLED",
    "parent": "projects/232342569935"
  }
}

Pola pogrubione pokazują mapowanie między schematem JSON a rzeczywistą odpowiedzią.

Jak widać na tym przykładzie, schematy mogą zawierać odniesienia do innych schematów. Jeśli tworzysz bibliotekę klienta, może Ci to pomóc w skutecznym modelowaniu obiektów interfejsu API w klasach modelu danych. W EnableServiceResponse przykładzie powyżej właściwość service odwołuje się do schematu o identyfikatorze GoogleApiServiceusageV1Service, czyli do innego schematu w dokumencie Discovery interfejsu Service Usage API. Właściwość GoogleApiServiceusageV1Service w zasobie EnableServiceResponse możesz zastąpić wartością schematu GoogleApiServiceusageV1Service (zwróć uwagę, że składnia $ref pochodzi ze specyfikacji schematu JSON).

Metody mogą też odwoływać się do schematów, gdy wskazują treść żądania i odpowiedzi. Więcej informacji znajdziesz w sekcji Metody.

Metody

Podstawą dokumentu opisującego są metody. Metody to operacje, które można wykonywać w interfejsie API. Sekcję methods znajdziesz w różnych miejscach dokumentu Discovery, m.in. na poziomie najwyższym (metody na poziomie 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ść, w której kluczem jest nazwa metody, a wartością – inne szczegóły dotyczące tej metody. W przykładzie poniżej udokumentowano 3 metody: get, enable i disable:

"methods": {
  "get": { //details about the "get" method },
  "enable": { //details about the "enable" method },
  "disable": { //details about the "disable" method }
}

W sekcji każdej metody znajdziesz szczegółowe informacje o różnych właściwościach tej metody. Oto przykład metody enable:

"enable": {
  "path": "v1/{+name}:enable",
  "request": {
    "$ref": "EnableServiceRequest"
  },
  "parameterOrder": [
    "name"
  ],
  "id": "serviceusage.services.enable",
  "response": {
    "$ref": "Operation"
  },
  "description": "Enable a service so that it can be used with a project.",
  "httpMethod": "POST",
  "flatPath": "v1/{v1Id}/{v1Id1}/services/{servicesId}:enable",
  "scopes": [
    "https://www.googleapis.com/auth/cloud-platform",
    "https://www.googleapis.com/auth/service.management"
  ],
  "parameters": {
    "name": {
      "location": "path",
      "description": "Name of the consumer and service to enable the service on. The `EnableService` and `DisableService` methods currently only support projects. Enabling a service requires that the service is public or is shared with the user enabling the service. An example name would be: `projects/123/services/serviceusage.googleapis.com` where `123` is the project number.",
      "required": true,
      "type": "string",
      "pattern": "^[^/]+/[^/]+/services/[^/]+$"
    }
  }
},

Ta sekcja zawiera ogólne informacje o metodzie, takie jak unikalny ID do identyfikowania metody, httpMethod do użycia i path metody (szczegółowe informacje o tym, jak używać właściwości path do obliczania pełnego adresu URL metody, znajdziesz w sekcji Tworzenie żądania). Oprócz tych ogólnych właściwości metody istnieje kilka właściwości, które łączą metodę z innymi sekcjami w dokumencie Discovery:

Zakresy

Sekcja auth zdefiniowana wcześniej w tej dokumentacji zawiera informacje o wszystkich zakresach obsługiwanych przez dany interfejs API. Jeśli metoda obsługuje jeden z tych zakresów, będzie zawierać tablicę zakresów. W tej tablicy znajduje się jeden wpis dla każdego zakresu obsługiwanego przez metodę.

Pamiętaj, że wybór zakresu autoryzacji do użycia w aplikacji zależy od różnych czynników, takich jak wywoływane metody i parametry przesyłane wraz z metodą. Dlatego decyzja o tym, którego zakresu użyć, należy do dewelopera. Discovery tylko dokumenty, których zakresy są prawidłowe dla danej metody.

Żądanie i odpowiedź

Jeśli metoda ma treść żądania lub odpowiedź, są one opisane odpowiednio w sekcjach request lub response. Na przykład w przypadku metody enable zawartość sekcji request wskazuje, że żądanie metody jest zdefiniowane przez schemat JSON o identyfikatorze EnableServiceRequest. Ten schemat znajdziesz w sekcji schematów najwyższego poziomu.

Parametry

Jeśli metoda ma parametry, które powinny być określone przez użytkownika, są one udokumentowane w sekcji parameters na poziomie metody. Ta sekcja zawiera mapowanie klucz/wartość, w którym nazwa parametru jest powiązana z jego szczegółami.

Na przykład metoda enable ma jeden parametr: name. Parametry mogą być umieszczane w path lub w adresie URL query. Właściwość location wskazuje, gdzie biblioteka klienta powinna umieścić parametr.

Istnieje wiele innych właściwości opisujących parametr, w tym typ danych parametrutype (przydatny w przypadku języków o silnym typowaniu), czy parametr jestrequired, oraz czy parametr jest wyliczeniem. Więcej informacji o tych właściwościach znajdziesz w dokumentacji referencyjnej tego interfejsu API.

Kolejność parametrów

Biblioteki klienta mogą mieć interfejsy o różnej strukturze. Jednym ze sposobów jest użycie metody z każdym parametrem interfejsu API w podpisie metody. JSON jest jednak formatem nieuporządkowanym, więc trudno jest programowo określić kolejność parametrów w sygnaturze metody. Tablica parameterOrder zapewnia stałą kolejność parametrów podczas wysyłania żądań. Tablica zawiera nazwy poszczególnych parametrów w kolejności ich ważności. Może zawierać parametry ścieżki lub zapytania, ale każdy parametr w tablicy jest wymagany.

Przesyłanie multimediów

Jeśli metoda obsługuje przesyłanie multimediów, takich jak obrazy, dźwięk lub wideo, lokalizacja i protokoły obsługiwane w przypadku przesyłania tych multimediów są opisane w sekcji mediaUpload. Ta sekcja zawiera szczegółowe informacje o obsługiwanych protokołach przesyłania i rodzajach multimediów, które można przesyłać.

Metoda enable nie zawiera sekcji mediaUpload. Typowa sekcja mediaUpload może wyglądać tak:

"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 to wartość logiczna, która określa, czy metoda obsługuje przesyłanie multimediów. Jeśli wartość to „true”, w sekcji mediaUpload znajdziesz informacje o rodzajach multimediów, które można przesłać.

Właściwość accept to lista zakresów multimediów, które określają, jakie typy MIME można przesyłać. Punkt końcowy pokazany w przykładzie powyżej akceptuje dowolny format obrazu.

Usługa maxSize ma maksymalny rozmiar przesyłanych plików. Wartość jest ciągiem znaków w jednostkach MB, GB lub TB. W przykładzie powyżej przesyłane pliki mogą mieć maksymalnie 10 MB. Pamiętaj, że ta wartość nie odzwierciedla pozostałego limitu miejsca na dane poszczególnych użytkowników w przypadku tego interfejsu API, więc nawet jeśli przesyłanie jest mniejsze niż maxSize, biblioteka klienta powinna być przygotowana na obsługę przesyłania, które nie powiedzie się z powodu niewystarczającej ilości miejsca.

W sekcji protocols znajdziesz listę protokołów przesyłania obsługiwanych przez daną metodę. Protokół simple polega na wysłaniu multimediów do danego punktu końcowego w ramach jednego żądania HTTP. Protokół resumable oznacza, że punkt końcowy podany w path identyfikatorze URI obsługuje protokół wznawialnego przesyłania. Jeśli właściwość multipart ma wartość true, punkt końcowy akceptuje przesyłanie wieloczęściowe, co oznacza, że żądanie JSON i media można połączyć w treści multipart/related i wysł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 należy ją rozwinąć tak samo jak właściwość path w przypadku metody, zgodnie z opisem w sekcji Tworzenie żądania.

Pobieranie multimediów

Jeśli metoda obsługuje pobieranie multimediów, takich jak obrazy, dźwięk lub wideo, jest to oznaczone parametrem supportsMediaDownload:

"supportsMediaDownload": true,

Podczas pobierania multimediów musisz ustawić parametr zapytania alt na media w adresie URL żądania.

Jeśli właściwość useMediaDownloadService metody API ma wartość true, wstaw /download przed servicePath, aby uniknąć przekierowania. Ścieżka pobierania to na przykład /download/youtube/v3/captions/{id}, jeśli połączenie servicePath i path daje /youtube/v3/captions/{id}. Zalecamy tworzenie adresu URL pobierania multimediów za pomocą parametru /download, nawet jeśli parametr useMediaDownloadService ma wartość false.

Typowe parametry

Dokument Discovery najwyższego poziomu zawiera właściwość parameters. Ta sekcja jest podobna do sekcji parametrów dla każdej metody, ale te parametry można stosować w przypadku dowolnej metody w interfejsie API.

Na przykład metody get i list interfejsu Service Usage API mogą mieć w parametrach żądania parametr prettyPrint, który sformatuje odpowiedź dla wszystkich tych metod w formacie czytelnym dla człowieka. Oto lista najczęstszych parametrów:

Dokumentacja wbudowana

Każdy dokument Discovery jest opatrzony adnotacjami w postaci kilku pól description, które zawierają wbudowaną dokumentację interfejsu API. Pola description można znaleźć w przypadku tych elementów interfejsu API:

• sam interfejs API,
• Zakresy protokołu OAuth
• Schematy zasobów
• Metody interfejsu API
• Parametry metody
• Akceptowane wartości niektórych parametrów

Pola te są szczególnie przydatne, jeśli chcesz użyć usługi Discovery API Google do wygenerowania dokumentacji biblioteki klienta w formacie czytelnym dla człowieka, np. JavaDoc.