Esta página foi traduzida pela API Cloud Translation.

Restringir o acesso à API com chaves da API

OpenAPI | gRPC

Pode usar chaves da API para restringir o acesso a métodos de 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 da API e também mostra como criar uma chave da API.

O Extensible Service Proxy (ESP) usa a API Service Control para validar uma chave de API e a respetiva associação a uma API ativada de um projeto. 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 está registado e não é adicionado ao cabeçalho do pedido. No entanto, pode ver o Google Cloud projeto ao qual um cliente está associado em Endpoints > Serviços, conforme descrito em Filtrar por um projeto de consumidor específico.

Para obter informações sobre 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 aceder a todos os métodos de uma API:

Abra o ficheiro openapi.yaml do projeto num editor de texto.
Em securityDefinitions:, adicione os valores api_key:, apiKey, key, query conforme mostrado no fragmento do código de exemplo:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Isto estabelece um "esquema de segurança" denominado api_key, que pode usar para proteger a API. Para outras api_keyopções de definição, consulte as limitações de definição da chave da API.
No nível superior do ficheiro (sem recuo nem aninhamento), adicione api_key: [] à diretiva security . Pode ter de adicionar a diretiva security ou esta pode já estar presente:
```
  security:
    - api_key: []
```
Esta diretiva aplica o esquema de segurança api_key a todos os métodos no ficheiro. Não coloque nada dentro dos parênteses retos. A especificação OpenAPI requer uma lista vazia para esquemas de segurança que não usam OAuth.

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

Para exigir uma chave da API para um método específico:

Abra o ficheiro openapi.yaml do projeto num editor de texto.
No nível superior do ficheiro (sem recuo nem aninhamento), adicione uma diretiva security vazia para a aplicar a toda a API:
```
security: []
```
Em securityDefinitions:, adicione os valores api_key:, apiKey, key, query conforme mostrado no fragmento do código de exemplo:
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
Isto estabelece um "esquema de segurança" denominado api_key, que pode usar para proteger a API. Para outras api_keyopções de definição, consulte as limitações de definição da chave da API.
Adicione api_key: [] à diretiva security na definição do método:
```
...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security:
  - api_key: []
  produces:
  ...
```
Esta diretiva aplica o esquema de segurança api_key ao método. Não coloque nada entre parênteses. A especificação OpenAPI requer uma lista vazia para esquemas de segurança que não usam OAuth.

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

Para desativar a validação da chave da API para um método específico, mesmo quando restringiu o acesso à API para a API:

Abra o ficheiro openapi.yaml do projeto num editor de texto.

Adicione uma diretiva security vazia na definição do método:

...
paths:
  "/echo":
post:
  description: "Echo back a given message."
  operationId: "echo"
  security: []
  produces:
  ...

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 no seguinte exemplo de curl:

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

onde ENDPOINTS_HOST e ENDPOINTS_KEY são variáveis de ambiente que contêm o nome de anfitrião da API e a chave da API, respetivamente.

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.

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:

No projeto Google Cloud no qual a sua API está configurada, conceda a cada utilizador a autorização para ativar a sua API.
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:

Crie um projeto separado para cada pessoa que liga.
Em cada projeto, ative a sua API e crie uma chave da API.
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:

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.
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:

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.
Atribuir a mesma chave da API a todos os autores da chamada.

Práticas recomendadas

Se usar chaves de API para proteger o acesso à sua API e aos dados do utilizador, certifique-se de que define a flag --service_control_network_fail_policy como close quando configurar as opções de arranque do proxy de serviço extensível V2 (ESPv2). O valor predefinido da flag é open.

O ESPv2 chama o Service Control para validar as chaves da API. Se ocorrerem falhas de rede ao estabelecer ligação ao Service Control e o ESPv2 não conseguir validar a chave da API, isto resulta na rejeição de quaisquer potenciais pedidos feitos à sua API com chaves fraudulentas.

Restringir o acesso à API com chaves da API Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.