Autenticar no Cloud Translation

Neste documento, descrevemos como autenticar para o Cloud Translation de maneira programática.

Para mais informações sobre a autenticação do Google Cloud, consulte a visão geral da autenticação.

Acesso à API

O Cloud Translation é compatível com o acesso programático. A maneira como você se autentica no Cloud Translation depende de como a API é acessada. Você pode acessar a API das seguintes maneiras:

Bibliotecas de clientes
REST

Bibliotecas de cliente

As bibliotecas de cliente do Cloud Translation fornecem suporte de alto nível de linguagem para autenticação programática no Cloud Translation. As bibliotecas de cliente oferecem suporte a Application Default Credentials (ADC). As bibliotecas procuram credenciais em um conjunto de locais definidos e as usam para autenticar solicitações à API. Com o ADC, é possível disponibilizar credenciais para seu aplicativo em uma variedade de ambientes, como desenvolvimento ou produção local, sem precisar modificar o código do aplicativo.

REST

É possível autenticar na API Cloud Translation usando as credenciais da CLI gcloud ou o Application Default Credentials. Para mais informações sobre autenticação para solicitações REST, consulte Autenticar usando REST. Para informações sobre os tipos de credenciais, consulte credenciais da CLI da gcloud e credenciais do ADC.

Chaves de API

As chaves de API fornecem uma maneira de associar uma chamada de API a um projeto, que é usado para fins de faturamento e cota, sem determinar a identidade do autor da chamada. As chaves de API só podem ser usadas com métodos de API compatíveis com chaves de API.

O Cloud Translation é compatível com chaves de API para os seguintes métodos de API:

Todos os métodos da API Cloud Translation - Basic (v2) são compatíveis com chaves de API, como translate e detect. A API Cloud Translation - Advanced (v3) não é compatível com chaves de API.

Para informações gerais sobre o uso de chaves de API, consulte Autenticar usando chaves de API.

Credenciais de usuário e ADC para o Cloud Translation

Uma maneira de fornecer credenciais ao ADC é usar a CLI gcloud para inserir suas credenciais de usuário em um arquivo de credenciais. Esse arquivo é colocado no sistema de arquivos local e encontrado pelo ADC. Em seguida, o ADC usa as credenciais de usuário fornecidas para autenticar as solicitações. Esse método é muito usado para desenvolvimento local.

Se você usar esse método, poderá encontrar um erro de autenticação ao tentar autenticar no Cloud Translation. Para mais informações sobre esse erro e como resolvê-lo, consulte Credenciais do usuário que não funcionam.

Configurar a autenticação do Cloud Translation

A configuração da autenticação depende do ambiente em que o código está sendo executado.

As opções a seguir para configuração da autenticação são as mais usadas. Para mais opções e informações sobre autenticação, consulte Autenticação no Google.

Antes de concluir estas instruções, conclua a configuração básica do Cloud Translation, conforme descrito em Configurar o Cloud Translation.

Para um ambiente de desenvolvimento local

É possível configurar credenciais para um ambiente de desenvolvimento local das seguintes maneiras:

Credenciais de usuário para bibliotecas de cliente ou ferramentas de terceiros
Credenciais do usuário para solicitações REST da linha de comando

Bibliotecas de cliente ou ferramentas de terceiros

Configure o Application Default Credentials (ADC) no ambiente local:

Instale a Google Cloud CLI e inicialize-a executando o seguinte comando:
```
gcloud init
```

Crie as credenciais de autenticação para sua Conta do Google:
```
gcloud auth application-default login
```
Observação: se a CLI gcloud exibir um aviso de que sua conta não tem a permissão serviceusage.services.use, alguns comandos da CLI gcloud podem não funcionar. Solicite ao administrador um papel de IAM de consumidor do Service Usage (roles/serviceusage.serviceUsageConsumer) e execute o comando a seguir:
```
gcloud auth application-default set-quota-project PROJECT_ID
```
Uma tela de login será exibida. Após o login, suas credenciais são armazenadas no arquivo de credenciais local usado pelo ADC.

Para mais informações sobre como trabalhar com o ADC em um ambiente local, consulte Ambiente de desenvolvimento local.

Solicitações REST usando a linha de comando

Ao fazer uma solicitação REST usando a linha de comando, use as credenciais da CLI gcloud incluindo gcloud auth print-access-token como parte do comando que envia a solicitação.

No exemplo a seguir, listamos as contas de serviço do projeto especificado. É possível usar o mesmo padrão em qualquer solicitação REST.

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

PROJECT_ID pelo ID do projeto no Google Cloud.

Para enviar a solicitação, expanda uma destas opções:

curl (Linux, macOS ou Cloud Shell)

Execute o seguinte comando:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts"

PowerShell (Windows)

Execute o seguinte comando:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts" | Select-Object -Expand Content

Para mais informações sobre como autenticar usando REST e gRPC, consulte Autenticar para usar REST. Para mais informações sobre a diferença entre as credenciais locais da ADC e as credenciais da CLI da gcloud, consulte Credenciais da CLI da gcloud e credenciais do ADC.

No Google Cloud

Para autenticar uma carga de trabalho em execução no Google Cloud, use as credenciais da conta de serviço anexada ao recurso de computação em que seu código está sendo executado. Por exemplo, é possível anexar uma conta de serviço a uma instância de máquina virtual (VM) do Compute Engine, a um serviço do Cloud Run ou a um job do Dataflow. Essa abordagem é o método de autenticação preferencial para códigos em execução em um recurso de computação do Google Cloud.

Para a maioria dos serviços, você precisa anexar a conta de serviço ao criar o recurso que executará o código. Não será possível adicionar ou substituir a conta de serviço mais tarde. O Compute Engine é uma exceção. Ele permite anexar uma conta de serviço a uma instância de VM a qualquer momento.

Use a CLI gcloud para criar uma conta de serviço e anexá-la ao recurso:

Instale a Google Cloud CLI e inicialize-a executando o seguinte comando:
```
gcloud init
```
Configure a autenticação:
1. Crie a conta de serviço:
```
gcloud iam service-accounts create SERVICE_ACCOUNT_NAME
```
  Substitua SERVICE_ACCOUNT_NAME por um nome para a conta de serviço.
2. Para conceder acesso ao projeto e aos recursos, conceda um papel à conta de serviço:
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE
```
  Substitua:
  - SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
  - PROJECT_ID: o ID do projeto em que você criou a conta de serviço
  - ROLE: o papel a ser concedido
  Observação: a flag --role afeta quais recursos sua conta de serviço pode acessar no projeto. É possível revogar esses papéis ou conceder outros papéis posteriormente. Em ambientes de produção, não conceda os papéis de proprietário, editor ou visualizador. Em vez disso, conceda um papel predefinido ou um papel personalizado que atenda às suas necessidades.
3. Para conceder outro papel à conta de serviço, execute o comando que você fez na etapa anterior.
4. Conceda à sua Conta do Google um papel que permita que você use os papéis da conta de serviço e anexe a conta de serviço a outros recursos:
```
gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser
```
  Substitua:
  - SERVICE_ACCOUNT_NAME: o nome da conta de serviço.
  - PROJECT_ID: o ID do projeto em que você criou a conta de serviço
  - USER_EMAIL: o endereço de e-mail da sua Conta do Google
Crie o recurso que executará o código e anexe a conta de serviço a ele. Por exemplo, se você usar o Compute Engine:
Crie uma instância do Compute Engine. Configure a instância da seguinte maneira:
- Substitua INSTANCE_NAME pelo nome de instância de sua preferência.
- Defina a sinalização --zone com a zona onde será criada a instância.
- Defina a sinalização --service-account como o endereço de e-mail da conta de serviço que você criou.
```
gcloud compute instances create INSTANCE_NAME --zone=ZONE --service-account=SERVICE_ACCOUNT_EMAIL
```

Para mais informações sobre a autenticação nas APIs do Google, consulte Autenticação no Google.

No local ou em outro provedor de nuvem

O método preferencial para configurar a autenticação de fora do Google Cloud é usar a federação de identidade da carga de trabalho. Para mais informações, consulte No local ou outro provedor de nuvem na documentação de autenticação.

Controle de acesso no Cloud Translation

Depois de autenticar o Cloud Translation, você precisa ter autorização para acessar os recursos do Google Cloud. O Cloud Translation usa o Identity and Access Management (IAM) para autorização.

Para mais informações sobre os papéis do Cloud Translation, consulte Controle de acesso com o IAM. Para mais informações sobre o IAM e a autorização, consulte Visão geral do IAM.

A seguir

Saiba mais sobre os métodos de autenticação do Google Cloud.
Veja uma lista de casos de uso de autenticação.