Este documento é destinado a desenvolvedores que querem criar bibliotecas de cliente, plug-ins de ambiente de desenvolvimento integrado e outras ferramentas para interagir com as APIs do Google. Com o serviço de descoberta de APIs do Google, você consegue realizar todas as ações acima expondo metadados legíveis por máquina sobre outras APIs do Google usando uma API simples. Este guia apresenta uma visão geral de cada seção do documento de descoberta, bem como dicas úteis sobre como usá-lo.
Todas as chamadas para a API são solicitações REST não autenticadas e baseadas em JSON que usam SSL. Em outras palavras, os URLs começam com https
.
Formato do documento de descoberta
Esta seção apresenta uma visão geral do documento de descoberta.
Todos os exemplos abaixo usam o documento de descoberta da API Service Usage.
Carregue o documento de descoberta da API Service Usage executando esta solicitação GET
:
GET https://serviceusage.s3nsapis.fr/$discovery/rest?version=v1
O formato de um documento de descoberta contém informações que se enquadram em seis categorias principais:
- Descrição básica da API.
- Informações de autenticação da API.
- Detalhes de recurso e esquema que descrevem os dados da API.
- Detalhes sobre os métodos da API.
- Informações sobre recursos personalizados compatíveis com a API.
- Documentação inline que descreve os elementos principais da API.
Cada uma dessas seções do documento de descoberta é descrita abaixo.
Descrição básica da API
O documento de descoberta contém um conjunto de properties específicas da API. Essas propriedades não necessariamente aparecem nesta ordem ou na mesma seção do documento de descoberta:
"id": "serviceusage:v1", "canonicalName": "Service Usage", "revision": "20240331", "servicePath": "", "baseUrl": "https://serviceusage.s3nsapis.fr/", "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.s3nsapis.fr/", "protocol": "rest"
Essas properties no nível da API contêm detalhes sobre uma versão específica de uma API, como name
, version
, title
e description
. O protocol
sempre tem um valor fixo de rest
, já que o serviço de descoberta de APIs só é compatível com métodos RESTful de acesso às APIs.
O campo servicePath
indica o prefixo do caminho dessa versão específica da API.
Autenticação
A seção auth
contém detalhes sobre os escopos de autenticação do OAuth 2.0 para a API. Para saber mais sobre como usar escopos com o OAuth 2.0, acesse Como usar o OAuth 2.0 para acessar as APIs do Google.
A seção auth
contém as seções oauth2
e scopes
aninhadas. A seção scopes
é um mapeamento de chave-valor do valor do escopo com mais detalhes sobre o escopo:
"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" } } } }
A seção auth
define apenas os escopos de uma API específica. Para saber como esses escopos são associados a um método de API, consulte a seção Métodos abaixo.
Recursos e esquemas
As operações de uma API atuam em objetos de dados chamados resources
. O documento de descoberta foi criado com base no conceito de recursos. Cada documento de descoberta tem uma seção resources
de nível superior que agrupa todos os recursos associados à API. Por exemplo, a API Service Usage tem um recurso services
e um recurso operations
no nível superior resources
:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
Dentro de cada seção de recursos, estão os métodos associados a eles. Por exemplo, a
API Service Usage tem seis métodos associados ao recurso
services
: get
, enable
, disable
, batchGet
,
batchEnable
e list
.
Os esquemas mostram como são os recursos em uma API. Cada documento de descoberta tem uma seção schemas
de nível superior, que contém um par de nome/valor de ID do esquema para o objeto. Os IDs dos esquemas são exclusivos por API e usados para identificar o esquema na
seção methods
do documento de descoberta. Por exemplo, aqui estão alguns dos esquemas no documento de descoberta da API Service Usage:
"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 } }
O serviço de descoberta de APIs usa o rascunho 03 do esquema JSON para as representações de esquema. Confira a seguir um snippet do esquema JSON para o recurso EnableServiceResponse
, junto com o GoogleApiServiceusagev1Service
ao qual ele faz referência. Junto com esses esquemas, há uma parte de uma resposta real para uma solicitação de ativação da API Pub/Sub (pubsub.googleapis.com
).
Esquema JSON de recurso EnableServiceResponse : |
Resposta real para ativar um serviço: |
"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" }, " |
"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": {} }, " |
Os campos em negrito mostram o mapeamento entre o esquema JSON e a resposta real.
Conforme mostrado neste exemplo, os esquemas podem conter referências a outros esquemas. Se você for criar uma biblioteca de cliente, isso poderá ajudar a modelar efetivamente os objetos de uma API nas suas classes de modelo de dados. No exemplo de EnableServiceResponse
acima, a propriedade service
é uma referência a um esquema com o ID GoogleApiServiceusageV1Service
, outro esquema no documento de descoberta da API Service Usage. É possível substituir a
propriedade GoogleApiServiceusageV1Service
no recurso EnableServiceResponse
pelo valor do esquema GoogleApiServiceusageV1Service
.
A sintaxe $ref
vem da especificação do
esquema JSON).
Os métodos também podem ter referência a esquemas ao indicar os respectivos corpos de solicitação e resposta. Consulte a seção Métodos para mais detalhes.
Métodos
O núcleo do documento de descoberta é criado com base em métodos. Métodos são as operações que podem ser realizadas em uma API. Você encontrará a seção methods
em várias áreas do documento de descoberta, incluindo no nível superior (que chamamos de métodos no nível da API) ou no nível de resources
.
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
Embora uma API possa ter métodos no nível da API, um recurso precisa ter uma seção methods
.
Cada seção methods
é um mapa de chave-valor do nome do método para outros detalhes sobre esse método. O exemplo abaixo documenta três métodos, get
, enable
e disable
:
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
Por fim, a seção de cada método detalha várias properties desse método. Veja um exemplo do método 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/[^/]+$" } } },
Esta seção contém detalhes gerais do método, como um ID
exclusivo para identificar o método, o httpMethod
a ser usado e o path
do método (para ver detalhes sobre como usar a property path
para calcular o URL completo do método, consulte a seção Criar uma solicitação). Além dessas properties gerais do método, há algumas que conectam o método a outras seções no documento de descoberta:
Escopos
A seção auth
definida anteriormente nesta documentação contém informações sobre todos os escopos compatíveis com uma API específica. Se um método for compatível com um desses escopos, ele terá uma matriz de escopos. Há uma só entrada nessa matriz para cada escopo compatível com o método.
Lembre-se de que escolher um escopo do Auth a ser usado no seu aplicativo depende de vários fatores, como quais métodos serão chamados e quais parâmetros serão enviados com o método. Portanto, a decisão de qual escopo usar cabe ao desenvolvedor. A descoberta só documenta quais escopos são válidos para um método.
Solicitação e resposta
Se o método tiver um corpo de solicitação ou resposta, eles serão documentados nas seções request
ou response
, respectivamente. Por exemplo, para o método enable
, o conteúdo da seção request
indica que a solicitação do método é
definida por um esquema JSON com um ID EnableServiceRequest
. Esse esquema pode ser encontrado na seção de esquemas de nível superior.
Parâmetros
Se um método tiver parâmetros que precisam ser especificados pelo usuário, esses parâmetros serão documentados na seção parameters
no nível do método. Esta seção contém um mapeamento de chave-valor do nome do parâmetro para mais detalhes sobre o parâmetro.
Por exemplo, há um parâmetro para o método enable
: name
.
Os parâmetros podem ser inseridos no path
ou na query
de URL. A propriedade location
indica onde a biblioteca de cliente precisa colocar o parâmetro.
Há muitas outras properties que descrevem o parâmetro, como type
de dados do parâmetro (útil para linguagens fortemente tipadas), caso o parâmetro seja required
e um tipo enumerado. Consulte a documentação de referência da API para mais detalhes sobre essas properties.
Ordem dos parâmetros
As bibliotecas de cliente podem estruturar as respectivas interfaces de várias maneiras. Uma dessas maneiras é ter um método com cada parâmetro de API na assinatura do método. No entanto, como JSON é um formato não ordenado, é difícil saber de modo programático como ordenar os parâmetros na assinatura do método. A matriz parameterOrder
tem uma ordem fixa de parâmetros para fazer solicitações. A matriz lista o nome de cada parâmetro em ordem de significância. Ela pode conter parâmetros de caminho ou de consulta, mas todos os parâmetros na matriz são obrigatórios.
Upload de mídia
Se um método for compatível com o upload de mídia, como imagens, áudio ou vídeo, o local e os protocolos compatíveis com upload dessa mídia serão documentados na seção mediaUpload
. Esta seção contém detalhes sobre os protocolos de upload compatíveis e informações sobre os tipos de mídia que podem ser transferidos.
O método enable
não contém uma seção mediaUpload
. No entanto, uma seção mediaUpload
típica pode ter a seguinte aparência:
"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" } } }
No exemplo acima, a property supportsMediaUpload
é um valor booleano que determina se o método é compatível com o upload de mídia. Se o valor for verdadeiro, a seção mediaUpload
documentará os tipos de mídia que podem ser transferidos.
A property accept
é uma lista de gamas de mídia que determinam quais tipos MIME são aceitáveis para upload. O endpoint mostrado no exemplo acima aceita qualquer formato da imagem.
A property maxSize
atingiu o tamanho máximo de um upload. O valor é uma string em unidades de MB, GB ou TB. No exemplo acima, os uploads são limitados a um tamanho máximo de 10 MB.
Lembre-se de que esse valor não reflete a cota de armazenamento restante de um usuário individual para essa API. Por isso, mesmo que o upload seja menor que maxSize
, a biblioteca de cliente ainda precisará estar preparada para lidar com um upload que falhar devido a espaço insuficiente.
A seção protocols
lista os protocolos de upload aceitos por um método. O protocolo simple
simplesmente faz o teste automático de inicialização (POST) da mídia para o endpoint especificado em uma única solicitação HTTP. O protocolo resumable
significa que o endpoint especificado no URI path
aceita o protocolo de upload retomável. Se a property multipart
for true
, o endpoint aceitará uploads de várias partes, o que significa que a solicitação JSON e a mídia podem ser unidas em um corpo de várias partes/relacionado e enviadas juntas. Lembre-se de que os protocolos simple
e resumable
podem aceitar uploads de várias partes.
A property path
é um modelo de URI e precisa ser expandida assim como a property path
do método, conforme descrito na seção Escrever uma solicitação.
Download de mídia
Se um método for compatível com o download de mídia, como imagens, áudio ou vídeo, isso será indicado pelo parâmetro supportsMediaDownload
:
"supportsMediaDownload": true,
Ao fazer o download de mídia, é necessário definir o parâmetro de consulta alt
como media
no URL da solicitação.
Se a property useMediaDownloadService
do método da API for true
, insira /download
antes de servicePath
para evitar um redirecionamento. Por exemplo, o caminho do download será /download/youtube/v3/captions/{id}
se a concatenação de servicePath
e path
for /youtube/v3/captions/{id}
. É recomendável criar um URL de download de mídia com /download
mesmo quando useMediaDownloadService
é falso.
Parâmetros comuns
O documento de descoberta de nível superior contém uma property parameters
. Esta seção é semelhante à seção de parâmetros de cada método, mas esses parâmetros podem ser aplicados a qualquer método na API.
Por exemplo, os métodos get
e list
da API Service Usage podem ter um parâmetro prettyPrint
nos parâmetros da solicitação, o que formatará a resposta para todos esses métodos em um formato legível por humanos. Veja a seguir uma lista de parâmetros comuns:
Parâmetro | Significado | Observações | Aplicabilidade |
---|---|---|---|
access_token |
O token do OAuth 2.0 para o usuário atual. |
|
|
alt |
Formato de dados da resposta. |
|
|
callback |
Função de retorno de chamada. |
|
|
fields |
Seletor com que é especificado um subconjunto de campos a ser incluído na resposta. |
|
|
key |
Chave de API. (OBRIGATÓRIO) |
|
|
prettyPrint |
Retorna uma resposta com recuos e quebras de linha. |
|
|
quotaUser |
Alternativa para userIp . |
|
|
userIp |
Endereço IP do usuário final para o qual a chamada de API está sendo feita. |
|
Documentação inline
Cada documento de descoberta é anotado com vários campos description
que fornecem a documentação inline da API. Os campos description
podem ser encontrados para os seguintes elementos da API:
- A API em si
- Escopos do OAuth
- Esquemas de recursos
- Métodos de API
- Parâmetros do método
- Valores aceitáveis para determinados parâmetros
Esses campos são especialmente úteis quando você quer usar o serviço de descoberta de APIs do Google para gerar uma documentação legível por humanos sobre uma biblioteca de cliente, por exemplo, JavaDoc.