Se você definir um requisito de chave na sua API, as solicitações para métodos, classes ou APIs protegidas serão rejeitadas a menos que elas tenham uma chave gerada no seu projeto ou em outros projetos de desenvolvedores com acesso para ativar sua API . O projeto em que a chave de API foi criada não é registrado nem adicionado ao cabeçalho da solicitação. No entanto, é possível visualizar o projeto do Google Cloud a que um cliente está associado. Basta usar a página Serviços do Endpoints, conforme descrito em Filtrar um projeto específico de consumidor.
Para mais informações sobre em qual projeto do Google Cloud uma chave de API precisa ser criada, consulte Como compartilhar APIs protegidas por chaves.
Como restringir acesso a todos os métodos da API
Para exigir o uso de uma chave de API para todas as chamadas na API, adicione apiKeyRequired = AnnotationBoolean.TRUE
à anotação @Api .
Por exemplo:
@Api(
name = "echo",
version = "v1",
apiKeyRequired = AnnotationBoolean.TRUE
)
public class Echo {
//API class and methods...
}
Restrição de acesso a métodos específicos da API
Para exigir o uso de uma chave de API em todas as chamadas para um método de API específico, adicione apiKeyRequired = AnnotationBoolean.TRUE
à sua anotação @ApiMethod.
Exemplo:
Para exigir o uso de uma chave de API em todas as chamadas para uma classe específica da API, adicione apiKeyRequired = AnnotationBoolean.TRUE
à anotação @ApiClass
.
Como remover a restrição de chave de API de um método
Para desativar a validação da chave em uma API ou um método de API, remova api_key_required=True
(Python) ou apiKeyRequired = AnnotationBoolean.TRUE
(Java) da API, do decorador do método ou da anotação. Em seguida, faça a compilação e a implantação novamente.
Como chamar uma API usando uma chave de API
Se uma API ou método de API exigir uma chave, forneça uma usando um parâmetro de consulta chamado key
, como 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}"
em que HOST
e API_KEY
são variáveis que contêm o nome de host da API e a chave de API, respectivamente. Substitua echo
pelo nome e v1
pela versão da API.
Como compartilhar APIs protegidas por chaves
As chaves de API são associadas ao projeto do Google Cloud em que foram criadas. Se você decidiu exigir uma chave para sua API, o projeto do Google Cloud em que a chave é criada vai depender das respostas às perguntas a seguir:
- Você precisa diferenciar os chamadores de sua API para poder usar recursos do Endpoints, como cotas?
- Todos os autores das chamadas da API têm os próprios projetos do Google Cloud?
- Você precisa configurar diferentes restrições de chave de API?
Use a árvore de decisões abaixo como guia para decidir em qual projeto do Google Cloud criar a chave de API.
Conceder permissão para ativar a API
Quando você precisa distinguir os autores das chamadas da sua API, e cada um tem o próprio projeto do Google Cloud, é possível conceder permissão aos principais para ativar a API no próprio projeto do Google Cloud. Dessa forma, os usuários da API podem criar a própria chave para usar com ela.
Por exemplo, digamos que sua equipe tenha criado uma API para uso interno por diversos programas cliente na empresa e cada um deles tenha o próprio projeto no Google Cloud. Para diferenciar os autores das chamadas da API, a chave de cada um deles precisa ser criada em um projeto do Google Cloud diferente. Dê permissão para que seus colegas ativem a API no projeto do Google Cloud ao qual o programa cliente está associado.
Veja como permitir que os usuários criem a própria chave de API:
- No projeto do Google Cloud em que a API está configurada, conceda a cada usuário a permissão para ativar a API.
- Entre em contato com os usuários para informar que eles podem ativar a API no projeto do Google Cloud e criar uma chave de API.
Criar um projeto separado do Google Cloud para cada autor da chamada
Quando você precisar diferenciar os autores das chamadas da API, mas nem todos tiverem projetos do Google Cloud, crie um projeto separado no Google Cloud e uma chave de API para cada um. Antes de criar os projetos, pense nos nomes deles para facilitar a identificação do cliente associado a cada um.
Por exemplo, digamos que você tenha clientes externos da API e não tenha ideia de como foram criados os programas clientes que chamam essa API. Talvez alguns clientes usem os serviços do Google Cloud e tenham um projeto dele e outros não. Para diferenciar os autores das chamadas, crie um projeto no Google Cloud e uma chave de API separados para cada um deles.
Para criar um projeto do Google Cloud e uma chave de API separados para cada autor da chamada:
- Crie um projeto separado para cada autor da chamada.
- Em cada projeto, ative a API e crie uma chave de API.
- Forneça a chave de API para cada autor da chamada.
Criar uma chave de API para cada autor da chamada
Quando você não precisa distinguir entre os autores das chamadas de API, mas quer adicionar restrições de chave de API, é possível criar uma chave de API separada para cada autor da chamada no mesmo projeto.
Veja como criar uma chave de API para cada autor da chamada no mesmo projeto:
- No projeto em que a API estiver ativada ou configurada, crie uma chave de API para cada cliente com as restrições necessárias.
- Forneça a chave de API para cada autor da chamada.
Criar uma chave de API para todos os autores das chamadas
Quando você não precisa distinguir entre os autores das chamadas de API e não precisa adicionar restrições, mas ainda quer exigir uma chave de API (para impedir o acesso anônimo, por exemplo), é possível criar uma chave para todos os autores de chamadas usarem.
Veja como criar uma chave de API para todos os autores das chamadas:- No projeto em que a API estiver ativada ou configurada, crie uma chave de API para todos os autores das chamadas.
- Forneça a mesma chave de API para cada autor da chamada.