Use a API Discovery

Este documento destina-se a programadores que querem escrever bibliotecas de clientes, plug-ins de IDEs e outras ferramentas para interagir com as APIs Google. O Google APIs Discovery Service permite-lhe fazer tudo o que foi indicado acima ao expor metadados legíveis por máquina sobre outras APIs Google através de uma API simples. Este guia oferece uma vista geral de cada secção do documento Discovery, bem como sugestões úteis sobre como usar o documento.

Todas as chamadas para a API são pedidos REST não autenticados baseados em JSON que usam SSL. Por outras palavras, os URLs começam com https.

Formato do documento de descoberta

Esta secção apresenta uma vista geral do documento Discovery.

Todos os exemplos abaixo usam o documento Discovery da API Service Usage. Pode carregar o documento de descoberta para a API Service Usage executando este pedido GET:

GET https://serviceusage.s3nsapis.fr/$discovery/rest?version=v1

O formato de um documento Discovery inclui informações que se enquadram em seis categorias principais:

• Descrição básica da API.
• Informações de autenticação para a API.
• Detalhes dos recursos e do esquema que descrevem os dados da API.
• Detalhes sobre os métodos da API.
• Informações sobre quaisquer funcionalidades personalizadas suportadas pela API.
• Documentação inline que descreve os elementos principais da API.

Cada uma destas secções do documento Discovery é descrita abaixo.

Descrição da API Basic

O documento Discovery contém um conjunto de propriedades específicas da API. Estas propriedades não aparecem necessariamente nesta ordem nem na mesma secçã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"

Estas propriedades ao nível da API incluem detalhes sobre uma versão específica de uma API, incluindo o name, version, title e description. O protocol tem sempre um valor fixo de rest, uma vez que o serviço de deteção de APIs só suporta métodos RESTful de acesso às APIs.

O campo servicePath indica o prefixo do caminho para esta versão específica da API.

Autenticação

A secção auth contém detalhes sobre os âmbitos de autorização do OAuth 2.0 para a API. Para saber mais acerca de como usar âmbitos com o OAuth 2.0, visite o artigo Usar o OAuth 2.0 para aceder às APIs Google.

A secção auth contém uma secção aninhada oauth2 e scopes. A secção scopes é um mapeamento de chave/valor do valor do âmbito para mais detalhes sobre o âmbito:

"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 secção auth define apenas os âmbitos de uma API específica. Para saber como estes âmbitos estão associados a um método da API, consulte a secção Métodos abaixo.

Recursos e esquemas

As operações de uma API atuam em objetos de dados denominados resources. O documento de descoberta é criado em torno do conceito de recursos. Cada documento Discovery tem uma secçã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 resources de nível superior:

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

Dentro de cada secção de recursos, encontram-se os métodos associados a esse recurso. Por exemplo, a API Service Usage tem seis métodos associados ao recurso services: get, enable, disable, batchGet, batchEnable e list.

Os esquemas indicam o aspeto dos recursos numa API. Cada documento de descoberta tem uma secção schemas de nível superior, que contém um par nome/valor do ID do esquema para o objeto. Os IDs de esquema são exclusivos por API e são usados para identificar de forma exclusiva o esquema na secção methods do documento Discovery. Por exemplo, seguem-se 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 deteção de APIs usa o esboço 03 do esquema JSON para as respetivas representações de esquemas. Segue-se um fragmento do esquema JSON para o recurso EnableServiceResponse, juntamente com o GoogleApiServiceusagev1Service ao qual faz referência. Juntamente com estes esquemas, encontra-se uma parte de uma resposta real a um pedido para ativar a API Pub/Sub (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"
  }
}

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 estiver a criar uma biblioteca cliente, isto pode ajudar a modelar eficazmente os objetos de uma API nas classes do seu modelo de dados. No exemplo 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. Pode substituir a propriedade GoogleApiServiceusageV1Service no recurso EnableServiceResponse pelo valor do esquema GoogleApiServiceusageV1Service (tenha em atenção que a sintaxe $ref provém da especificação do esquema JSON).

Os métodos também podem fazer referência a esquemas quando indicam os respetivos corpos de pedido e resposta. Consulte a secção Métodos para ver mais detalhes.

Métodos

O núcleo do documento Discovery é criado em torno de métodos. Os métodos são as operações que podem ser realizadas numa API. Encontra a secção methods em várias áreas do documento Discovery, incluindo ao nível superior (que denominamos métodos ao nível da API) ou ao nível 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 ao nível da API, um recurso tem de ter uma secção methods.

Cada secçã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 último, a secção de cada método detalha várias propriedades sobre esse método. Segue-se 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 secção contém detalhes gerais do método, como um ID exclusivo para identificar o método, o httpMethod a usar e o path do método (para detalhes sobre como usar a propriedade path para calcular o URL completo do método, consulte a secção Componha um pedido). Além destas propriedades gerais do método, existem algumas propriedades que associam o método a outras secções no documento Discovery:

Âmbitos

A secção auth definida anteriormente nesta documentação contém informações sobre todos os âmbitos suportados por uma API específica. Se um método suportar um destes âmbitos, tem um array de âmbitos. Existe uma entrada nesta matriz para cada âmbito suportado pelo método.

Tenha em atenção que a escolha de um âmbito de autorização a usar na sua aplicação depende de vários fatores, como: que métodos estão a ser chamados e que parâmetros são enviados juntamente com o método. Por conseguinte, a decisão sobre o âmbito a usar é deixada ao programador. Apenas documentos de descoberta cujos âmbitos são válidos para um método.

Pedido e resposta

Se o método tiver um corpo de pedido ou de resposta, estes são documentados nas secções request ou response, respetivamente. Por exemplo, para o método enable, o conteúdo da secção request indica que o pedido do método é definido por um esquema JSON com um ID de EnableServiceRequest. Este esquema pode ser encontrado na secção de esquemas de nível superior.

Parâmetros

Se um método tiver parâmetros que devem ser especificados pelo utilizador, estes parâmetros são documentados na secção parameters ao nível do método. Esta secção contém um mapeamento de chave/valor do nome do parâmetro para mais detalhes sobre esse parâmetro.

Por exemplo, existe um parâmetro para o método enable: name. Os parâmetros podem ser colocados no path ou no URL query; a propriedade location indica onde a biblioteca de cliente deve colocar o parâmetro.

Existem muitas outras propriedades que descrevem o parâmetro, incluindo os dados do parâmetro type (úteis para linguagens fortemente tipadas), se o parâmetro é required e se o parâmetro é uma enumeração. Consulte a documentação de referência desta API para ver mais detalhes sobre estas propriedades.

Ordem dos parâmetros

Existem muitas formas de as bibliotecas de cliente estruturarem as respetivas interfaces. Uma forma é ter um método com cada parâmetro da API na assinatura do método. No entanto, uma vez que o JSON é um formato não ordenado, é difícil saber programaticamente como ordenar os parâmetros na assinatura do método. A matriz parameterOrder fornece uma ordem de parâmetros fixa para fazer pedidos. A matriz indica o nome de cada parâmetro por ordem de importância. Pode conter parâmetros de caminho ou de consulta, mas todos os parâmetros na matriz são obrigatórios.

Carregamento de conteúdo multimédia

Se um método suportar o carregamento de conteúdo multimédia, como imagens, áudio ou vídeo, a localização e os protocolos suportados para carregar esse conteúdo multimédia estão documentados na secção mediaUpload. Esta secção contém detalhes sobre os protocolos de carregamento suportados e informações sobre os tipos de suportes que podem ser carregados.

O método enable não contém uma secção mediaUpload. No entanto, uma secção mediaUpload típica pode ter o seguinte aspeto:

"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 propriedade supportsMediaUpload é um valor booleano que determina se o método suporta o carregamento de conteúdo multimédia. Se o valor for verdadeiro, a secção mediaUpload documenta os tipos de suportes que podem ser carregados.

A propriedade accept é uma lista de intervalos de multimédia que determinam que tipos MIME são aceitáveis para carregamento. O ponto final apresentado no exemplo acima aceita qualquer formato de imagem.

A propriedade maxSize tem o tamanho máximo de um carregamento. O valor é uma string em unidades de MB, GB ou TB. No exemplo acima, os carregamentos estão limitados a um tamanho máximo de 10 MB. Tenha em atenção que este valor não reflete a quota de armazenamento restante de um utilizador individual para essa API, pelo que, mesmo que o carregamento seja inferior a maxSize, a biblioteca de cliente deve continuar a estar preparada para processar um carregamento que falhe devido a espaço insuficiente.

A secção protocols apresenta os protocolos de carregamento que um método suporta. O protocolo simple envia simplesmente o conteúdo multimédia para o ponto final indicado num único pedido HTTP. O protocolo resumable implica que o ponto final indicado no URI path suporta o protocolo de carregamento retomável . Se a propriedade multipart for true, o ponto final aceita carregamentos multipartes, o que significa que o pedido JSON e o conteúdo multimédia podem ser incluídos num corpo multipart/related e enviados em conjunto. Tenha em atenção que os protocolos simple e resumable podem suportar carregamentos multipartes.

A propriedade path é um modelo de URI e deve ser expandida tal como a propriedade path para o método, conforme descrito na secção Componha um pedido.

Transferência de conteúdo multimédia

Se um método suportar a transferência de multimédia, como imagens, áudio ou vídeo, isso é indicado pelo parâmetro supportsMediaDownload:

"supportsMediaDownload": true,

Quando transfere conteúdo multimédia, tem de definir o parâmetro de consulta alt como media no URL do pedido.

Se a propriedade useMediaDownloadService do método API for true, insira /download antes de servicePath para evitar um redirecionamento. Por exemplo, o caminho de transferência é /download/youtube/v3/captions/{id} se a concatenação de servicePath e path for /youtube/v3/captions/{id}. Recomendamos que construa o URL de transferência de multimédia com /download, mesmo quando useMediaDownloadService é falso.

Parâmetros comuns

O documento Discovery de nível superior contém uma propriedade parameters. Esta secção é semelhante à secção de parâmetros para cada método. No entanto, estes 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 do pedido, que formata a resposta para todos esses métodos num formato legível por humanos. Segue-se uma lista de parâmetros comuns:

Documentação inline

Cada documento Discovery é anotado com vários campos description que fornecem documentação inline para a API. Pode encontrar os campos description nos seguintes elementos da API:

• A própria API
• âmbitos do OAuth
• Esquemas de recursos
• Métodos da API
• Parâmetros do método
• Valores aceitáveis para determinados parâmetros

Estes campos são especialmente úteis se quiser usar o Google APIs Discovery Service para gerar documentação legível para humanos para uma biblioteca cliente, por exemplo, o JavaDoc.