En este documento se describe cómo definir un proyecto de cuota para tus APIs basadas en clientes. Para obtener información sobre qué es el proyecto de cuota, cómo definir la API de cuota y cómo se determina el proyecto de cuota, consulta Acerca del proyecto de cuota.
Las solicitudes pueden fallar si haces una solicitud a una API basada en cliente y no se puede identificar el proyecto de cuota. El proyecto de cuota se puede definir de varias formas y se verifica comprobando las siguientes opciones. Aparecen en orden de precedencia:
Especificado en la solicitud: el proyecto de cuota que se especificó en la solicitud. Si usas bibliotecas de cliente, también puedes usar variables de entorno en tus solicitudes.
Clave de API: si usas una clave de API para proporcionar credenciales para una solicitud, el proyecto asociado a la clave de API se usa como proyecto de cuota.
Credenciales de la CLI de Google Cloud: si usas la CLI de gcloud para obtener tu token de acceso y te has autenticado en la CLI de gcloud con tus credenciales de usuario, el proyecto compartido de la CLI de gcloud se usa a veces como proyecto de cuota. Sin embargo, no todas las APIs basadas en clientes recurren al proyecto compartido.
Cuenta de servicio: si la entidad de seguridad de la llamada a la API es una cuenta de servicio (incluida la suplantación de identidad), el proyecto asociado a la cuenta de servicio se utiliza como proyecto de cuota.
Federación de identidades de Workforce: si la entidad de seguridad de la API es un usuario de la federación de identidades de Workforce, se utiliza el proyecto de usuario del grupo de trabajo como proyecto de cuota.
Si ninguna de las comprobaciones anteriores da como resultado un proyecto de cuota, la solicitud falla.
Hay varias formas de definir proyectos de cuota. Si el proyecto de cuota se especifica mediante más de un método, se aplica el siguiente orden de prioridad:
- De forma programática
- Variable de entorno
- Credenciales utilizadas para autenticar la solicitud.
Definir el proyecto de cuota mediante programación
Puedes definir explícitamente el proyecto de cuota en tu aplicación. Este método anula todas las demás definiciones. El principal usado para autenticar la solicitud debe tener el permiso necesario en el proyecto de cuota especificado.
La forma de definir el proyecto de cuota de forma programática depende de si usas una biblioteca de cliente, la CLI de gcloud o una solicitud de la API REST.
Biblioteca de cliente
Puedes definir el valor del proyecto de cuota mediante opciones de cliente al crear el cliente. Este método es útil si quieres controlar el valor de tu proyecto de cuota desde tu aplicación, independientemente del entorno en el que se ejecute.
Para obtener más información sobre cómo implementar las opciones de cliente, consulta la documentación de tu biblioteca de cliente.
CLI de gcloud
Puede definir el proyecto de cuota para todos los comandos de gcloud CLI mediante la propiedad billing/quota_project en la configuración de gcloud CLI. También puedes definir el proyecto de cuota de un comando específico mediante la marca --billing-project, que tiene prioridad sobre la propiedad de configuración.
Para obtener más información sobre las configuraciones de la CLI de gcloud, consulta la documentación de gcloud config.
Para obtener más información sobre la marca --billing-project, consulta la --billing-projectdocumentación.
Solicitud REST
Puede especificar el proyecto de cuota en una solicitud REST mediante el encabezado x-goog-user-project.
La entidad de seguridad que hace la solicitud debe tener los permisos necesarios en el proyecto de cuota.
Para obtener más información y código de ejemplo, consulta Definir el proyecto de cuota con una solicitud REST.
Definir el proyecto de cuota mediante una variable de entorno
Las bibliotecas de cliente de algunos lenguajes admiten la configuración del proyecto de cuota mediante una variable de entorno. Este enfoque puede ser útil si quieres definir el proyecto de cuota de forma diferente en shells distintos o anular el proyecto de cuota asociado a la credencial. La entidad de seguridad de cualquier solicitud debe tener los permisos necesarios en el proyecto de cuota especificado por la variable de entorno.
La variable de entorno depende del idioma:
| Idioma | Variable de entorno |
|---|---|
| C++ |
|
| C# |
|
| Go |
|
| Java |
|
| Node.js |
|
| Python |
|
| PHP |
|
| Ruby | No disponible |
Definir el proyecto de cuota mediante credenciales de autenticación
Si no se especifica el proyecto de cuota, las bibliotecas de autenticación intentan determinarlo a partir de las credenciales que se han usado en la solicitud. Este proceso depende del tipo de credenciales que se hayan usado para autenticar la solicitud:
- Cuenta de servicio: el proyecto asociado a la cuenta de servicio se usa como proyecto de cuota.
- Credenciales de usuario: en un entorno de desarrollo local, las credenciales de aplicación predeterminadas buscan tus credenciales de usuario en el archivo ADC local. En ese archivo también se puede especificar un proyecto de cuota. Si has configurado el proyecto en tu configuración de la CLI de Google Cloud y tienes los permisos necesarios en ese proyecto, el proyecto de cuota se definirá de forma predeterminada al crear el archivo ADC local. También puedes definir el proyecto de cuota de ADC mediante el comando
auth application-default set-quota-project. - Claves de API: cuando usas una clave de API para proporcionar credenciales para una solicitud, el proyecto asociado a la clave de API se usa como proyecto de cuota.
Permisos necesarios para definir y usar el proyecto de cuota
Para obtener el permiso que necesitas para definir un proyecto como proyecto de cuota o usar ese proyecto de cuota en una solicitud,
pide a tu administrador que te conceda el rol de gestión de identidades y accesos
Consumidor de Uso de Servicio (roles/serviceusage.serviceUsageConsumer)
en el proyecto.
Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.
Este rol predefinido contiene el permiso serviceusage.services.use
, que es necesario para definir un proyecto como proyecto de cuota o para usar ese proyecto de cuota en una solicitud.
También puedes obtener este permiso con roles personalizados u otros roles predefinidos.
Si usas un proyecto que has creado como proyecto de cuota, tendrás los permisos necesarios.
Para obtener más información sobre los permisos, consulta Permisos de cuota.
Definir el usuario de cuota
Algunas APIs también limitan el número de solicitudes por usuario, que es diferente de las cuotas por proyecto descritas en las secciones anteriores de este documento.
De forma predeterminada, el sistema usa la entidad autenticada. Si no hay ninguna entidad autenticada, el sistema usa la dirección IP del cliente.
Si necesitas anular el usuario de cuota, puedes definir el parámetro quotaUser a través de los parámetros del sistema de la API Cloud. Si especificas un quotaUser o un X-Goog-Quota-User, debes usar una clave de API válida con restricciones de dirección IP para identificar el proyecto de cuota. De lo contrario, se ignora el parámetro quotaUser.
Para obtener más información sobre los parámetros del sistema de la API de Cloud y sus definiciones, consulta la tabla de definiciones de los parámetros del sistema.
Siguientes pasos
- Información sobre el proyecto de cuota
- Más información sobre las credenciales predeterminadas de la aplicación
- Consulta más información sobre la autenticación.
- Información sobre las cuotas