Usa la API de Discovery

Este documento está dirigido a desarrolladores que deseen escribir bibliotecas 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, ya que expone metadatos procesables sobre otras APIs de Google a través de una API simple. En esta guía, se proporciona una descripción general de cada sección del documento de descubrimiento, así como sugerencias útiles sobre cómo usarlo.

Todas las llamadas a la API son solicitudes de REST no autenticadas y basadas en JSON que usan SSL. En otras palabras, las URLs comienzan con https.

Formato del documento de descubrimiento

En esta sección, se ofrece una descripción general del documento de descubrimiento.

Todos los ejemplos que aparecen a continuación usan el documento de descubrimiento de la API de Service Usage. Puedes cargar el documento de descubrimiento para la API de Service Usage si ejecutas esta solicitud GET: 

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

El formato de un documento de descubrimiento incluye información que se divide en seis categorías principales:

Cada una de estas secciones del documento de descubrimiento se describe a continuación.

Descripción básica de la API

El documento de descubrimiento contiene un conjunto de propiedades específicas de la API. Estas propiedades no necesariamente aparecen en este orden o en la misma sección del documento de descubrimiento:

"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 propiedades a nivel de API incluyen detalles sobre una versión particular de una API, incluidos name, version, title y description. El protocol siempre tiene un valor fijo de rest, ya que el servicio de descubrimiento de las APIs solo admite métodos RESTful para acceder a las APIs.

El campo servicePath indica el prefijo de la ruta de acceso para esta versión de API en particular.

Autenticación

La sección auth contiene detalles sobre los permisos de autenticación de OAuth 2.0 para la API. Con el objetivo de obtener más información sobre cómo usar los permisos con OAuth 2.0, visita Usa OAuth 2.0 para acceder a las APIs de Google.

La sección auth contiene una sección oauth2 y scopes anidada. La sección scopes es una asignación de clave-valor del valor del permiso a más detalles sobre el permiso: 

"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 en particular. Para obtener información sobre cómo se asocian estos permisos con un método de API, consulta la sección Métodos a continuación.

Recursos y esquemas

Las operaciones de una API actúan sobre los objetos de datos llamados resources. El documento de descubrimiento se basa en el concepto de recursos. Cada documento de descubrimiento tiene una sección resources de nivel superior que agrupa todos los recursos asociados con la API. Por ejemplo, la API de Service Usage tiene un recurso services y 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 con ese recurso. Por ejemplo, la API de Service Usage tiene seis métodos asociados con el recurso services: get, enable, disable, batchGet, batchEnable y list.

Los esquemas te indican cómo son los recursos en una API. Cada documento de descubrimiento tiene una sección schemas de nivel superior, que contiene un par nombre/valor del ID de esquema del objeto. Los IDs de esquema son únicos por API y se usan para identificar de manera inequívoca el esquema en la sección methods del documento de descubrimiento. Por ejemplo, estos son algunos de los esquemas en el documento de descubrimiento de la API de 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
  }
}

El Servicio de descubrimiento de las APIs usa JSON Schema borrador-03 para sus representaciones de esquema. El siguiente es un fragmento del esquema JSON para el recurso EnableServiceResponse, junto con el GoogleApiServiceusagev1Service al que hace referencia. Junto a estos esquemas, se muestra una parte de una respuesta real para una solicitud de habilitación de la API de Pub/Sub (pubsub.googleapis.com).

Esquema de JSON del recurso EnableServiceResponse: 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"
    },
    "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"
  }
}

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 compilas una biblioteca cliente, esto puede ayudarte a modelar de manera eficaz los objetos de una API en tus clases de modelos de datos. En el ejemplo de EnableServiceResponse anterior, la propiedad service es una referencia a un esquema con el ID GoogleApiServiceusageV1Service, otro esquema en el documento de descubrimiento de la API de Service Usage. Puedes sustituir la propiedad GoogleApiServiceusageV1Service en el recurso EnableServiceResponse por el valor del esquema GoogleApiServiceusageV1Service (ten en cuenta que la sintaxis $ref proviene del Especificación del esquema de JSON).

Los métodos también pueden hacer referencia a esquemas cuando indican sus cuerpos de solicitud y respuesta. Consulta la sección Métodos para obtener más información.

Métodos

El núcleo del documento de descubrimiento se basa en los métodos. Los métodos son las operaciones que se pueden realizar en una API. Encontrarás la sección methods en varias áreas del documento de descubrimiento, incluso en el nivel superior (que denominamos métodos de 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
        }
      }
    }
  }
}

Si bien 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 par clave-valor desde el nombre del método hasta otros detalles sobre ese método. En el siguiente ejemplo, 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 ese método. 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 usará y el path del método (para obtener más detalles sobre cómo usar la path para calcular la URL completa del método, consulta la sección Redacta una solicitud). Además de estas propiedades generales del método, hay algunas propiedades que conectan el método con otras secciones del documento de descubrimiento:

Permisos

La sección auth definida antes en esta documentación contiene información sobre todos los permisos compatibles con una API en particular. Si un método admite uno de estos permisos, tendrá un array de permisos. Hay una entrada en este array para cada permiso que admite el método.

Ten en cuenta que elegir un permiso de autenticación para usar en tu aplicación depende de varios factores, como a qué métodos se llaman y qué parámetros se envían junto con el método. Por lo tanto, la decisión del permiso que se usará le queda al desarrollador. Descubre solo los documentos cuyos permisos son válidos para un método.

Solicitud y respuesta

Si el método tiene un cuerpo de solicitud o respuesta, estos se documentan en las secciones request o response, respectivamente. Por ejemplo, para 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 un ID de 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 el usuario debe especificar, estos se documentan en la sección parameters a nivel del método. En esta sección, se muestra una asignación de par clave-valor del nombre del parámetro con el objetivo de obtener más detalles sobre él.

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 la biblioteca cliente debe colocar el parámetro.

Hay muchas otras propiedades que describen el parámetro, incluidos los datos del parámetro type (útiles para lenguajes con tipado fuerte), si el parámetro es required y si el parámetro es una enumeración. Consulta la documentación de referencia de esta API para obtener más detalles sobre estas propiedades.

Orden de los parámetros

Existen muchas formas de que las bibliotecas cliente estructuran sus interfaces. Una forma es tener un método con cada parámetro de la API en la firma del método. Sin embargo, debido a que JSON es un formato desordenado, es difícil saber de manera programática cómo ordenar los parámetros en la firma del método. El array parameterOrder proporciona un orden de parámetros fijo para realizar solicitudes. El array muestra el nombre de cada parámetro en orden de importancia; puede contener parámetros de ruta o consulta, pero todos los parámetros del array son obligatorios.

Carga de archivos multimedia

Si un método admite la carga de archivos multimedia, como imágenes, audio o video, la ubicación y los protocolos admitidos para subir ese contenido se documentan en la sección mediaUpload. Esta sección contiene detalles sobre los protocolos de carga compatibles y la información sobre los tipos de contenido multimedia que pueden subirse.

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 carga de contenido multimedia. Si el valor es verdadero, la sección mediaUpload documenta los tipos de contenido multimedia que se pueden subir.

La propiedad accept es una lista de rangos de medios que determinan qué tipos de MIME son aceptables para subir. El extremo que se muestra en el ejemplo anterior aceptará cualquier formato de imagen.

La propiedad maxSize tiene el tamaño máximo de una carga. El valor es una cadena en unidades de MB, GB o TB. En el ejemplo anterior, las cargas 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 individual para esa API, por lo que, incluso si la carga es inferior a maxSize, la biblioteca cliente aún debe estar preparada para manejar una carga que falla, ya que de espacio insuficiente.

En la sección protocols, se enumeran los protocolos de carga que admite un método. El protocolo simple simplemente publica los medios en el extremo determinado en una sola solicitud HTTP. El protocolo resumable implica que el extremo proporcionado en el URI path admite el protocolo de carga reanudable. Si la propiedad multipart es true, el extremo acepta cargas multiparte, lo que significa que tanto la solicitud JSON como los medios pueden unirse juntos en un multiparte/relacionado. y se envían juntos. Ten en cuenta que los protocolos simple y resumable pueden admitir cargas multiparte.

La propiedad path es una plantilla de URI y debe expandirse al igual que la propiedad path para el método, como se describe en la sección Redacta una solicitud.

Descarga de archivos multimedia

Si un método admite la descarga de archivos multimedia, como imágenes, audio o video, eso se indica mediante el parámetro supportsMediaDownload: 

"supportsMediaDownload": true,

Cuando descargues contenido multimedia, debes configurar el parámetro de consulta alt como media en la URL de la solicitud.

Si la propiedad useMediaDownloadService del método de la API es true, inserta /download antes de servicePath para evitar un redireccionamiento. 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 una URL de descarga de contenido multimedia con /download, incluso cuando useMediaDownloadService es falso.

Parámetros comunes

El documento de descubrimiento de nivel superior contiene una propiedad parameters. Esta sección es similar a la sección de parámetros para cada método; sin embargo, estos parámetros se pueden aplicar a cualquier método en la API.

Por ejemplo, los métodos get y list de la API de Service Usage pueden tener un parámetro prettyPrint en los parámetros de solicitud, que dará formato a la respuesta de todos esos métodos en un formato legible por humanos. A continuación, se muestra una lista de parámetros comunes:

Parámetro Significado Notas Aplicabilidad
access_token Token de OAuth 2.0 para el usuario actual
alt

Formato de datos para la respuesta.
  • Valores válidos: json, atom, csv.
  • Valor predeterminado: varía según la API.
  • No todos los valores están disponibles para cada API.
  • Se aplica a todas las operaciones para todos los recursos.
callback Función de devolución de llamada
  • Nombre de la función de devolución de llamada de JavaScript que maneja la respuesta
  • Se usa en las solicitudes JSON-P de JavaScript.
fields Selector que especifica un subconjunto de campos para incluir en la respuesta.
  • Se usa para mejorar el rendimiento.
key Clave de API (OBLIGATORIA)
  • Obligatoria, a menos que proporciones un token de OAuth 2.0.
  • Tu clave de API identifica tu proyecto y proporciona acceso a la API, la cuota y los informes.
  • Obtén la clave de API de tu proyecto en la Consola de APIs.
prettyPrint Muestra una respuesta con sangrías y saltos de línea.
  • Muestra la respuesta en un formato legible si es true.
  • Valor predeterminado: varía según la API.
  • Cuando el valor es false, puede reducirse el tamaño de la carga útil de la respuesta, lo que podría mejorar el rendimiento en algunos entornos.
quotaUser Alternativa a userIp.
  • Permite aplicar las cuotas por usuario desde una aplicación del lado del servidor, incluso cuando se desconoce la dirección IP del usuario. Esto puede ocurrir, por ejemplo, con aplicaciones que ejecutan trabajos cron en App Engine en nombre de un usuario.
  • Puedes elegir cualquier cadena arbitraria que identifique de forma inequívoca a un usuario, pero debe tener un máximo de 40 caracteres.
  • Anula userIp si se proporcionan ambos.
  • Obtén más información sobre la limitación de uso.
userIp Dirección IP del usuario final para el cual se realiza la llamada a la API
  • Permite aplicar las cuotas por usuario cuando se llama a la API desde una aplicación del lado del servidor.
  • Obtén más información sobre la limitación de uso.

Documentación intercalada

Cada documento de descubrimiento está anotado con varios campos description que proporcionan documentación intercalada para la API. Los campos description se pueden encontrar para los siguientes elementos de la API:

  • La API
  • Alcances de OAuth
  • Esquemas de recursos
  • Métodos de la API
  • Parámetros de método
  • Valores aceptables para determinados parámetros

Estos campos son especialmente útiles si deseas usar el Servicio de descubrimiento de las APIs de Google con el objetivo de generar documentación legible para una biblioteca cliente, por ejemplo, JavaDoc.