Este documento está dirigido a desarrolladores que quieran escribir bibliotecas de cliente, complementos de IDE y otras herramientas para interactuar con las APIs de Google. El servicio de descubrimiento de APIs de Google te permite hacer todo lo anterior exponiendo metadatos legibles por máquina sobre otras APIs de Google a través de una API sencilla. En esta guía se ofrece un resumen de cada sección del documento de Discovery, así como consejos útiles sobre cómo usarlo.
Todas las llamadas a la API son solicitudes REST basadas en JSON y no autenticadas que usan SSL. Es decir, las URLs empiezan por https.
Formato del documento de descubrimiento
En esta sección se ofrece una descripción general del documento de Discovery.
En todos los ejemplos que se muestran a continuación se usa el documento de descubrimiento de la API Service Usage.
Para cargar el documento de descubrimiento de la API Usage de Servicio, ejecuta esta solicitud GET:
GET https://serviceusage.googleapis.com/$discovery/rest?version=v1
El formato de un documento de descubrimiento incluye información que se divide en seis categorías principales:
- Descripción básica de la API.
- Información sobre la autenticación de la API.
- Detalles de los recursos y del esquema que describen los datos de la API.
- Detalles sobre los métodos de la API.
- Información sobre las funciones personalizadas que admite la API.
- Documentación insertada que describe los elementos clave de la API.
A continuación, se describe cada una de estas secciones del documento de Discovery.
Descripción básica de la API
El documento de descubrimiento contiene un conjunto de propiedades específicas de la API. Estas propiedades no tienen por qué aparecer en este orden ni en la misma sección del documento de descubrimiento:
"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"
Estas propiedades a nivel de API incluyen detalles sobre una versión concreta de una API, como name, version, title y description. El protocol siempre tiene el valor fijo rest, ya que el servicio de descubrimiento de APIs solo admite métodos RESTful para acceder a las APIs.
El campo servicePath indica el prefijo de ruta de esta versión concreta de la API.
Autenticación
La sección auth contiene información detallada sobre los permisos de autenticación de OAuth 2.0 de la API. Para obtener más información sobre cómo usar los permisos con OAuth 2.0, consulta el artículo Usar OAuth 2.0 para acceder a las APIs de Google.
La sección auth contiene las secciones anidadas oauth2 y scopes. La sección scopes es una asignación de clave/valor del valor del ámbito a más
detalles sobre el á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" } } } }
La sección auth solo define los permisos de una API concreta. Para saber cómo se asocian estos
ámbitos a un método de API, consulta la sección Métodos que se incluye más abajo.
Recursos y esquemas
Las operaciones de una API actúan sobre objetos de datos llamados resources. El documento de descubrimiento
se basa en el concepto de recursos. Cada documento de descubrimiento tiene una sección de nivel superior resources que agrupa todos los recursos asociados a la API. Por ejemplo, la API Service Usage tiene un recurso services y un recurso operations en el nivel superior resources:
"resources": { "services": { // Methods associated with the services resource } "operations": { // Methods associated with the operations resource } }
Dentro de cada sección de recursos se encuentran los métodos asociados a ese recurso. Por ejemplo, la API Service Usage tiene seis métodos asociados al recurso services: get, enable, disable, batchGet, batchEnable y list.
Los esquemas te indican cómo son los recursos de una API. Cada documento de Discovery tiene una sección schemas de nivel superior que contiene un par nombre/valor de ID de esquema a objeto. Los IDs de esquema son únicos por API y se usan para identificar de forma exclusiva el esquema en la sección methods del documento de Discovery. Por ejemplo, estos son algunos de los esquemas del documento de descubrimiento de la API Usage Service:
"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 } }
El servicio de descubrimiento de APIs utiliza JSON
Schema draft-03 para sus representaciones de esquemas. A continuación, se muestra un fragmento del esquema JSON del recurso EnableServiceResponse, junto con el GoogleApiServiceusagev1Service al que hace referencia. Junto a estos esquemas, se muestra una parte de una respuesta real a una solicitud para habilitar la API Pub/Sub (pubsub.googleapis.com).
EnableServiceResponse Esquema JSON de recursos: |
Respuesta real para habilitar un servicio: |
"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": {} }, " |
Los campos en negrita muestran la asignación entre el esquema JSON y la respuesta real.
Como se muestra en este ejemplo, los esquemas pueden contener referencias a otros esquemas. Si estás creando una biblioteca de cliente, esto puede ayudarte a modelar de forma eficaz los objetos de una API en las clases de tu modelo de datos. En el ejemplo de EnableServiceResponse anterior, la propiedad service
es una referencia a un esquema con el ID GoogleApiServiceusageV1Service,
otro esquema del documento de descubrimiento de la API de Uso de Servicio. Puede sustituir la propiedad GoogleApiServiceusageV1Service del recurso EnableServiceResponse por el valor del esquema GoogleApiServiceusageV1Service (tenga en cuenta que la sintaxis $ref procede de la especificación del esquema JSON).
Los métodos también pueden hacer referencia a esquemas al indicar los cuerpos de sus solicitudes y respuestas. Consulta la sección Métodos para obtener más información.
Métodos
El núcleo del documento de descubrimiento se basa en métodos. Los métodos son las operaciones que se pueden realizar en una API. Encontrarás la sección methods en varias partes del documento de descubrimiento, como en el nivel superior (que llamamos métodos a nivel de API) o en el nivel resources.
"methods": { // API-level methods } "resources": { "resource1": { "methods": { // resource-level methods } "resources": { "nestedResource": { "methods": { // methods can even be found in nested-resources } } } } }
Aunque una API puede tener métodos a nivel de API, un recurso debe tener una sección methods.
Cada sección methods es un mapa de clave-valor que va del nombre del método a otros detalles sobre ese método. En el ejemplo siguiente se documentan tres métodos: get, enable y disable.
"methods": { "get": { //details about the "get" method }, "enable": { //details about the "enable" method }, "disable": { //details about the "disable" method } }
Por último, en la sección de cada método se detallan varias propiedades sobre él. A continuación, se muestra un ejemplo del 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 sección contiene detalles generales del método, como un ID único para identificar el método, el httpMethod que se va a usar y el path del método (para obtener más información sobre cómo usar la propiedad path para calcular la URL completa del método, consulta la sección Crear una solicitud). Además de estas propiedades generales de los métodos, hay algunas propiedades que conectan el método con otras secciones del documento de Discovery:
Ámbitos
La sección auth definida anteriormente en esta documentación contiene información sobre todos los ámbitos admitidos por una API concreta. Si un método admite uno de estos ámbitos, tendrá un array de ámbitos. Hay una entrada en esta matriz para cada ámbito admitido por el método.
Ten en cuenta que la elección de un ámbito de autorización para usarlo en tu aplicación depende de varios factores, como los métodos a los que se llama y los parámetros que se envían junto con el método. Por lo tanto, el desarrollador decide qué ámbito usar. Discovery solo documenta los ámbitos que son válidos para un método.
Solicitud y respuesta
Si el método tiene un cuerpo de solicitud o de respuesta, se documenta en las secciones request
o response, respectivamente. Por ejemplo, en el método enable, el contenido de la sección request indica que la solicitud del método se define mediante un esquema JSON con el ID EnableServiceRequest. Este esquema se puede encontrar en la sección de esquemas de nivel superior.
Parámetros
Si un método tiene parámetros que debe especificar el usuario, estos parámetros se documentan en la sección parameters a nivel de método. Esta sección contiene una asignación de clave-valor del nombre del parámetro a más detalles sobre ese parámetro.
Por ejemplo, hay un parámetro para el método enable: name.
Los parámetros pueden ir en path o en la URL query. La propiedad location indica dónde debe colocar el parámetro la biblioteca de cliente.
Hay muchas otras propiedades que describen el parámetro, incluidos los datos del parámetro type (útil para lenguajes con tipado fuerte), si el parámetro es required y si el parámetro es un enum. Consulta la documentación de referencia de esta API para obtener más información sobre estas propiedades.
Orden de los parámetros
Las bibliotecas de cliente pueden estructurar sus interfaces de muchas formas. Una forma es tener un método con cada parámetro de la API en la firma del método. Sin embargo, como JSON es un formato sin ordenar, es difícil saber mediante programación cómo ordenar los parámetros en la firma del método. La matriz parameterOrder proporciona un orden de parámetros fijo para hacer solicitudes. La matriz muestra el nombre de cada parámetro por orden de importancia. Puede contener parámetros de ruta o de consulta, pero todos los parámetros de la matriz son obligatorios.
Subida de contenido multimedia
Si un método admite la subida de contenido multimedia, como imágenes, audio o vídeo, la ubicación y los protocolos admitidos para subir ese contenido se documentan en la sección mediaUpload. En esta sección se explica qué protocolos de subida se admiten y qué tipos de contenido multimedia se pueden subir.
El método enable no contiene una sección mediaUpload. Sin embargo, una sección mediaUpload típica podría tener el siguiente aspecto:
"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" } } }
En el ejemplo anterior, la propiedad supportsMediaUpload es un valor booleano que determina si el método admite la subida de contenido multimedia. Si el valor es true, la sección mediaUpload indica los tipos de contenido multimedia que se pueden subir.
La propiedad accept es una lista de intervalos de contenido multimedia que determinan qué tipos MIME se pueden subir. El endpoint que se muestra en el ejemplo anterior aceptará cualquier formato de imagen.
La propiedad maxSize tiene el tamaño máximo de una subida. El valor es una cadena en unidades de MB, GB o TB. En el ejemplo anterior, las subidas están limitadas a un tamaño máximo de 10 MB.
Ten en cuenta que este valor no refleja la cuota de almacenamiento restante de un usuario concreto para esa API, por lo que, aunque la subida sea inferior a maxSize, la biblioteca cliente debe estar preparada para gestionar una subida que falle por falta de espacio.
En la sección protocols se indican los protocolos de subida que admite un método. El protocolo simple simplemente envía el contenido multimedia al endpoint indicado en una sola solicitud HTTP. El protocolo resumable implica que el endpoint proporcionado en el URI path admite el protocolo de subida reanudable. Si la propiedad multipart es true, el endpoint acepta subidas multiparte, lo que significa que tanto la solicitud JSON como el contenido multimedia se pueden envolver juntos en un cuerpo multipart/related y enviarse juntos. Ten en cuenta que los protocolos simple y resumable pueden admitir subidas multiparte.
La propiedad path es una plantilla de URI y debe ampliarse igual que la propiedad path del método, tal como se indica en la sección Redactar una solicitud.
Descarga de contenido multimedia
Si un método admite la descarga de contenido multimedia, como imágenes, audio o vídeo, se indica mediante el parámetro supportsMediaDownload:
"supportsMediaDownload": true,
Cuando descargues contenido multimedia, debes asignar el valor media al parámetro de consulta alt en la URL de la solicitud.
Si la propiedad useMediaDownloadService del método de la API es true, inserte /download antes de servicePath para evitar una redirección. Por ejemplo, la ruta de descarga es /download/youtube/v3/captions/{id} si la concatenación de servicePath y path es /youtube/v3/captions/{id}. Se recomienda crear la URL de descarga de contenido multimedia con /download aunque useMediaDownloadService sea false.
Parámetros comunes
El documento de Discovery de nivel superior contiene una propiedad parameters. Esta sección es similar a la sección de parámetros de cada método, pero estos parámetros se pueden aplicar a cualquier método de la API.
Por ejemplo, los métodos get y list de la API Usage de Servicios pueden tener un parámetro prettyPrint en los parámetros de la solicitud, que dará formato a la respuesta de todos esos métodos en un formato legible. A continuación, se muestra una lista de los parámetros más habituales:
| Parámetro | Significado | Notas | Aplicabilidad |
|---|---|---|---|
access_token |
Token de OAuth 2.0 para el usuario actual. |
|
|
alt |
Formato de los datos de la respuesta. |
|
|
callback |
Función de devolución de llamada. |
|
|
fields |
Selector que especifica un subconjunto de campos para incluirlos en la respuesta. |
|
|
key |
Clave de API. (OBLIGATORIO) |
|
|
prettyPrint |
Devuelve la respuesta con sangrías y saltos de línea. |
|
|
quotaUser |
Alternativa a userIp. |
|
|
userIp |
Dirección IP del usuario final para el que se está haciendo la llamada a la API. |
|
Documentación insertada
Cada documento de descubrimiento se anota con una serie de campos description que
proporcionan documentación insertada para la API. Los campos description se pueden encontrar en los siguientes elementos de la API:
- La API en sí
- permisos de OAuth
- Esquemas de recursos
- Métodos de API
- Parámetros de método
- Valores aceptables para determinados parámetros
Estos campos son especialmente útiles si quieres usar el servicio de detección de las APIs de Google para generar documentación legible por humanos para una biblioteca de cliente (por ejemplo, JavaDoc).