Restringir o acesso à API com chaves da API

Pode usar chaves da API para restringir o acesso a métodos da API específicos ou a todos os métodos numa API. Esta página descreve como restringir o acesso à API aos clientes que têm uma chave de API e também mostra como criar uma chave de API.

Se definir um requisito de chave da API na sua API, os pedidos ao método, à classe ou à API protegidos são rejeitados, a menos que tenham uma chave gerada no seu projeto ou noutros projetos pertencentes a programadores aos quais concedeu acesso para ativar a sua API. O projeto no qual a chave da API foi criada não é registado nem adicionado ao cabeçalho do pedido. No entanto, pode ver o Google Cloud projeto ao qual um cliente está associado na página Serviços de pontos finais, conforme descrito em Filtrar por um projeto de consumidor específico.

Para saber em que Google Cloud projeto deve ser criada uma chave da API, consulte o artigo Partilhar APIs protegidas por chave da API.

Restringir o acesso a todos os métodos da API

Para exigir uma chave da API para todas as chamadas à API, adicione apiKeyRequired = AnnotationBoolean.TRUE à sua anotação@Api. Por exemplo:

@Api(
  name = "echo",
  version = "v1",
  apiKeyRequired = AnnotationBoolean.TRUE
  )
public class Echo {
//API class and methods...
}

Restringir o acesso a métodos de API específicos

Para exigir uma chave da API para todas as chamadas para um método de API específico, adicione apiKeyRequired = AnnotationBoolean.TRUE à sua anotação@ApiMethod. Por exemplo:

@ApiMethod(name = "echo_api_key", path = "echo_api_key", apiKeyRequired = AnnotationBoolean.TRUE)
public Message echoApiKey(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}

Para exigir uma chave da API para todas as chamadas a uma classe de API específica, adicione apiKeyRequired = AnnotationBoolean.TRUE à sua anotação @ApiClass.

Remover a restrição da chave da API para um método

Para desativar a validação da chave da API para uma API ou um método da API, remova api_key_required=True (Python) ou apiKeyRequired = AnnotationBoolean.TRUE (Java) do decorador ou da anotação da API ou do método. Em seguida, volte a compilar e implementar.

Chamar uma API através de uma chave da API

Se uma API ou um método API exigir uma chave da API, forneça a chave através de um parâmetro de consulta denominado key, conforme mostrado neste exemplo de cURL:

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}"

onde HOST e API_KEY são variáveis que contêm o nome do anfitrião da API e a chave da API, respetivamente. Substitua echo pelo nome da sua API e v1 pela versão da sua API.

Partilhar APIs protegidas por chave da API

As chaves da API estão associadas ao Google Cloud projeto no qual foram criadas. Se decidiu exigir uma chave da API para a sua API, o Google Cloud projeto no qual a chave da API é criada depende das respostas às seguintes perguntas:

  • Precisa de distinguir entre os autores da chamada da sua API para poder usar funcionalidades dos Endpoints, como quotas?
  • Todos os autores de chamadas da sua API têm os seus próprios Google Cloud projetos?
  • Precisa de configurar diferentes restrições da chave da API?

Pode usar a seguinte árvore de decisão como um guia para decidir em que Google Cloud projeto criar a chave da API.

Árvore de decisões da chave da API

Conceda autorização para ativar a API

Quando precisa de distinguir entre os autores da chamada da sua API e cada autor da chamada tem o seu próprio projeto, pode conceder aos principais autorização para ativar a API no seu próprio projeto. Google Cloud Google Cloud Desta forma, os utilizadores da sua API podem criar a sua própria chave da API para utilização com a sua API.

Por exemplo, suponhamos que a sua equipa criou uma API para utilização interna por vários programas cliente na sua empresa e que cada programa cliente tem o seu próprio projeto. Google CloudPara distinguir entre os autores da chamada da sua API, a chave da API de cada autor da chamada tem de ser criada num projeto Google Cloud diferente. Pode conceder aos seus colegas autorização para ativar a API no projeto Google Cloud ao qual o programa cliente está associado.

Para permitir que os utilizadores criem a sua própria chave da API:

  1. No projeto Google Cloud no qual a sua API está configurada, conceda a cada utilizador a autorização para ativar a sua API.
  2. Contacte os utilizadores e informe-os de que podem ativar a sua API no respetivo projeto Google Cloud e criar uma chave da API.

Crie um Google Cloud projeto separado para cada pessoa que liga

Quando precisa de distinguir os autores das chamadas da sua API e nem todos os autores das chamadas têm projetos, pode criar um projeto e uma chave da API separados para cada autor da chamada. Google Cloud Google Cloud Antes de criar os projetos, pense nos nomes dos projetos para poder identificar facilmente o autor da chamada associado ao projeto.

Por exemplo, suponhamos que tem clientes externos da sua API e não tem ideia de como foram criados os programas cliente que chamam a sua API. Talvez alguns dos clientes usem Google Cloud serviços e tenham um Google Cloud projeto, e talvez alguns não. Para distinguir os autores da chamada, tem de criar um Google Cloud projeto e uma chave da API separados para cada autor da chamada.

Para criar um Google Cloud projeto e uma chave da API separados para cada autor da chamada:

  1. Crie um projeto separado para cada pessoa que liga.
  2. Em cada projeto, ative a sua API e crie uma chave da API.
  3. Dê a chave da API a cada autor da chamada.

Crie uma chave da API para cada autor da chamada

Quando não precisa de distinguir entre os autores da chamada da sua API, mas quer adicionar restrições de chaves da API, pode criar uma chave da API separada para cada autor da chamada no mesmo projeto.

Para criar uma chave da API para cada autor da chamada no mesmo projeto:

  1. No projeto no qual a sua API está configurada ou num projeto no qual a API está ativada, crie uma chave da API para cada cliente que tenha as restrições da chave da API de que precisa.
  2. Dê a chave da API a cada autor da chamada.

Crie uma chave da API para todos os autores da chamada

Quando não precisa de distinguir entre os autores da chamada da sua API e não precisa de adicionar restrições de API, mas ainda quer exigir uma chave da API (para impedir o acesso anónimo, por exemplo), pode criar uma chave da API para todos os autores da chamada usarem.

Para criar uma chave da API para todos os autores da chamada:
  1. No projeto no qual a sua API está configurada ou num projeto no qual a API está ativada, crie uma chave da API para todos os autores da chamada que tenha as restrições da chave da API de que precisa.
  2. Atribuir a mesma chave da API a todos os autores da chamada.

O que se segue?