Controlo de admissão

Introdução

Esta página descreve como usar a API Service Control v2 para o controlo de admissão para serviços geridos que estão integrados com a infraestrutura de serviços. Destina-se a produtores de serviços que queiram integrar profundamente os respetivos serviços com o Google Cloud.

A Service Infrastructure é uma plataforma fundamental para os programadores produzirem, gerirem, protegerem e consumirem APIs e serviços. Usa um modelo de utilização de serviços simples e genérico: um consumidor consome um serviço gerido por um produtor. Todas as APIs Google e as APIs Google Cloud usam este modelo, uma vez que também são criadas com base na infraestrutura de serviços.

Quando um cliente acede a um serviço, todas as entidades envolvidas no acesso normalmente requerem uma verificação do estado e das políticas, incluindo o consumidor, o serviço, o produtor, o utilizador, a aplicação, a rede e os recursos. Com a infraestrutura de serviços, este processo chama-se controlo de admissão, que inclui autenticação, autorização, auditoria, limitação de taxa e muito mais.

Nota: para a terminologia usada nesta página, consulte o glossário de APIs.

API Service Control v2

A API Service Control v2 oferece um método simples services.check que oferece controlo de admissão a todos os serviços integrados com a infraestrutura de serviços. Este método permite-lhe fazer o seguinte numa única chamada de método:

• Verificação do estado
  • Estado de abuso
  • Estado de faturação
  • Estado do consumidor
  • Estado do serviço
  • Ativação de serviços
• Autenticação
  • Chave de acesso do Google OAuth
  • JWT assinado da conta de serviço Google
• Autorização
  • Identity and Access Management (IAM)
• Auditoria
  • Registos de auditoria do Cloud. O registo de auditoria está associado ao serviço "externalaudit.googleapis.com".

Quando um serviço chama a API Service Control, o produtor também é um consumidor da API Service Control. Por conseguinte, o método services.check também executa o controlo de admissão na chamada para a API Service Control.

Para que um serviço chame a API Service Control, tem de ativar a API Service Control no projeto do produtor e ter as autorizações adequadas no serviço. Para mais informações, consulte os artigos Introdução às APIs Cloud e Controlo de acesso do Service Control.

Atributos de pedido

Quando um cliente acede a um serviço, o serviço tem de abstrair o acesso em um ou mais pedidos de API que podem ser verificados com o controlo de admissão. Na maioria dos casos, estes acessos são, de facto, pedidos API reais. Noutros casos, o acesso pode envolver tarefas de importação de dados complexas ou consultas SQL, e o serviço tem de modelar o acesso em termos de um conjunto de pedidos de API virtuais e realizar o controlo de admissão em cada pedido.

Para realizar o controlo de admissão através da API Service Control, o serviço tem de chamar o método services.check com os atributos de pedido necessários. A tabela seguinte lista os atributos necessários para o controlo de admissão. Para ver a especificação completa, consulte AttributeContext.

Attibute	Descrição	Exemplo
origin.ip	O endereço IP do autor da chamada.	"1.2.3.4"
api.service	O nome do serviço da API.	"endpointsapis.appspot.com"
api.operation	O nome do método da API.	"google.example.hello.v1.HelloService.GetHello"
api.version	A string da versão da API.	"v1"
api.protocol	O nome do protocolo da API.	"https"
request.id	Um ID do pedido exclusivo.	"123e4567-e89b-12d3-a456-426655440000"
request.time	A hora do pedido.	"2019-07-31T05:20:00Z"
request.method	O nome do método HTTP.	"POST"
request.scheme	O esquema de URL.	"https"
request.host	O cabeçalho do anfitrião HTTP.	"endpointsapis.appspot.com"
request.path	O caminho de URL.	"/v1/hello"
request.headers	Os cabeçalhos do pedido HTTP. Os cabeçalhos necessários são "authorization", "user-agent", "origin" e "referer".
resource.name	O nome do recurso de destino.	"projects/123/topics/news-feed"

Atributos do recurso

Quando um cliente acede a um serviço, o acesso pode envolver um ou mais recursos no serviço, como ler um objeto ou criar uma instância de VM. O serviço pode usar o controlo de admissão da infraestrutura de serviços para o controlo de acesso em recursos, suportado pela IAM e pelos registos de auditoria do Cloud. Se o seu serviço não precisar de controlo de acesso, pode ignorar esta secção.

Para o controlo de acesso, um serviço tem de transmitir atributos de recursos ao método services.check juntamente com os atributos de solicitação. A tabela seguinte mostra os atributos de recursos necessários para o controlo de acesso.

Attibute	Descrição	Exemplo
name	O nome do recurso.	"projects/123/locations/global/instances/instance-1"
type	O tipo de recurso. O formato é "{service}/{Kind}".	"endpointsapis.appspot.com/Instance"
permission	A autorização de recursos. O formato é "{service}/{kinds}.{verb}".	"endpointsapis.appspot.com/instances.get"

Para desempenho e eficiência, o método services.check permite-lhe verificar várias autorizações num único recurso numa única chamada.

Realizar o controlo de admissão

Depois de implementar a configuração do serviço na API Service Management e o serviço estiver pronto para processar pedidos de clientes, pode começar a chamar services.check para o serviço implementado. Deve chamar services.check para realizar o controlo de admissão sempre que o seu serviço receber um pedido.

Para experimentar rapidamente o controlo de admissão, pode usar o comando gcurl para chamar o método services.check. Consulte o artigo Introdução à API Service Control para ver os passos de configuração iniciais.

O exemplo seguinte mostra como usar o comando gcurl para chamar services.check atravé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
{
}

A resposta do método services.check indica se o controlo de admissão foi aprovado. Se passar, a resposta deve estar vazia. Se falhar, o status na resposta contém informações de erro que o serviço deve devolver ao cliente. Muitas vezes, o serviço tem de traduzir as informações de erro para o seu próprio formato. O serviço também pode usar as informações para fins de registo e monitorização.

Para serviços de produção, deve usar uma das bibliotecas cliente fornecidas pela Google para chamar a API Service Control. Estas bibliotecas oferecem uma excelente usabilidade e processam automaticamente a funcionalidade comum, como a autenticação. Para mais informações, consulte o artigo Bibliotecas de cliente explicadas.