Control de admisión

Introducción

En esta página, se describe cómo usar la API de Control de servicios v2 para el control de admisión en los servicios administrados que están integrados a Service Infrastructure. Está dirigido a los productores de servicios que desean integrar sus servicios por completo a Google Cloud.

Service Infrastructure es una plataforma fundamental para que los desarrolladores produzcan, administren, protejan y consuman las API y los servicios. Utiliza un modelo de uso de servicio simple y genérico: un consumidor consume un servicio que administra un productor. Todas las API de Google y las API de Google Cloud usan este modelo, ya que también se compilan en Service Infrastructure.

Cuando un cliente accede a un servicio, todas las entidades involucradas en el acceso, por lo general, requiere una verificación de estado y política, que incluye el consumidor, el servicio, el productor, el usuario, la aplicación, la red y los recursos. En Service Infrastructure, este proceso se denomina control de admisión, que incluye autenticación, autorización, auditoría, límite de frecuencia y mucho más.

Nota: Para la terminología que se usa en esta página, consulta Glosario de la API.

API de Control de servicios v2

La API de Control de servicios v2 proporciona un método services.check simple que suministra control de admisión para todos los servicios integrados en Service Infrastructure. Este método le permite hacer las siguientes tareas en una sola llamada al método:

• Verificación de estados
  • Estado de uso indebido
  • Estado de facturación
  • Estado del consumidor
  • Estado un servicio
  • Habilitación de servicios
• Autenticación
  • Token de acceso de Google OAuth
  • JWT firmado de la cuenta de servicio de Google
• Autorización
  • Administración de identidades y accesos (IAM)
• Auditoría
  • Registros de auditoría de Cloud El registro de auditoría está asociado con el servicio “externalaudit.googleapis.com”.

Cuando un servicio llama a la API de Control de servicios, el productor también es un consumidor de esa API. Por lo tanto, el método services.check también realiza el control de admisión en la llamada a la API de Control de servicios.

Para que un servicio llame a la API de Control de servicios, debe habilitar esa API en el proyecto del productor y tener los permisos adecuados en el servicio. Para obtener más información, consulte Introducción de las API de Cloud y Control de acceso del Control de servicios.

Atributos de solicitud

Cuando un cliente accede a un servicio, este debe abstraer el acceso en una o más solicitudes a la API que se pueden verificar con el control de admisión. En la mayoría de los casos, tales accesos son de hecho solicitudes reales a la API. En otros casos, el acceso puede consistir en consultas de SQL o trabajos de importación de datos complejos, y el servicio necesita modelar el acceso en términos de un conjunto de solicitudes virtuales a la API y realizar el control de admisión en cada solicitud.

Para realizar el control de admisión con la API de Control de servicios, el servicio debe llamar al método services.check con los atributos de solicitud requeridos. En la siguiente tabla, se enumeran los atributos necesarios para el control de admisión. Para ver la especificación completa, consulta AttributeContext.

Atributo	Descripción	Ejemplo
origin.ip	La dirección IP del emisor de la llamada.	“1.2.3.4”
api.service	El nombre del servicio de API.	"endpointsapis.appspot.com"
api.operation	El nombre del método de la API.	"google.example.hello.v1.HelloService.GetHello"
api.version	La string de versión de la API.	"v1"
api.protocol	El nombre del protocolo de la API.	"https"
request.id	Un ID de solicitud único.	"123e4567-e89b-12d3-a456-426655440000"
request.time	La hora de la solicitud.	"2019-07-31T05:20:00Z"
request.method	El nombre del método HTTP.	"POST"
request.scheme	El esquema de URL.	"https"
request.host	El encabezado del host HTTP.	"endpointsapis.appspot.com"
request.path	La ruta de URL.	"/v1/hello"
request.headers	Los encabezados de la solicitud HTTP. Los encabezados requeridos son "autorización", "usuario-agente", "origen", "referente".
resource.name	El nombre del recurso de destino.	"projects/123/topics/news-feed"

Atributos de recursos

Cuando un cliente accede a un servicio, el acceso puede involucrar uno o más recursos dentro del servicio, como leer un objeto o crear una instancia de VM. El servicio puede usar el control de admisión de la Service Infrastructure para el control de acceso en los recursos, compatible con IAM y los Registros de auditoría de Cloud. Si tu servicio no necesita el control de acceso, puedes omitir esta sección.

Para el control de acceso, un servicio necesita pasar atributos de recursos al método services.check junto con los atributos de la solicitud. En la siguiente tabla, se muestran los atributos de recursos necesarios para el control de acceso.

Atributo	Descripción	Ejemplo
name	El nombre del recurso.	"projects/123/locations/global/instances/instance-1"
type	El tipo del recurso. El formato es “{service}/{Kind}”.	"endpointsapis.appspot.com/Instance"
permission	El permiso del recurso. El formato es “{service}/{kinds}.{verb}”.	"endpointsapis.appspot.com/instances.get"

Para obtener rendimiento y eficiencia, el método services.check te permite verificar varios permisos en un solo recurso en una llamada.

Realiza el control de admisión

Una vez que hayas implementado la configuración de servicio en la API de Administración de servicios y tu servicio esté listo a fin de entregar solicitudes de clientes, puedes comenzar a llamar a services.check para tu servicio implementado. Debes llamar a services.check para realizar el control de admisión cada vez que tu servicio reciba una solicitud.

Para experimentar rápidamente con el control de admisión, puede usar el comando de gcurl para llamar al método services.check. Consulta Comienza a usar la API de Control de servicios para conocer los pasos de configuración iniciales.

En el siguiente ejemplo, se muestra cómo usar el comando gcurl para llamar a services.check a través de HTTP.

gcurl -d '{
  "service_config_id": "latest",
  "attributes": {
    "origin": {
      "ip": "1.2.3.4"
    },
    "api": {
      "service": "endpointsapis.appspot.com",
      "operation": "google.example.hello.v1.HelloService.GetHello",
      "version": "v1",
      "protocol": "https"
    }
  },
  "request": {
    "id": "123e4567-e89b-12d3-a456-426655440000",
    "time": "2019-07-31T05:20:00Z",
    "scheme": "https",
    "host": "endpointsapis.appspot.com"
    "headers": {
      "authorization": "Bearer xxx",
      "user-agent": "curl/1.0"
    }
  },
  "resources": [
  ]
}' https://servicecontrol.googleapis.com/v2/services/endpointsapis.appspot.com:check
{
}

La respuesta del método services.check indica si el control de admisión se aprobó. Si se aprueba, la respuesta debe estar vacía. Si no se aprueba, el status en la respuesta contiene información sobre el error que el servicio debe mostrarle al cliente. Por lo general, el servicio necesita traducir la información sobre el error a su propio formato. El servicio también puede usar la información para fines de registro y supervisión.

Para los servicios de producción, debe usar una de las bibliotecas cliente proporcionadas por Google para llamar a la API de Control de servicios. Dichas bibliotecas proporcionan una gran usabilidad y manejan funciones comunes automáticamente, como la autenticación. Para obtener más información, consulte Explicación de las bibliotecas cliente.