Como autenticar na API

Nesta página, explicamos como autorizar solicitações para a API Cloud Healthcare.

Como conseguir um arquivo de chave da conta de serviço

Para criar uma conta de serviço e fazer o download de um arquivo de chave:

Console do Cloud

  1. No Console do Cloud, acesse a página Criar chave da conta de serviço.

    Acessar página "Criar chave da conta de serviço"
  2. Na lista Conta de serviço, selecione Nova conta de serviço.
  3. No campo Nome da conta de serviço, insira um nome.
  4. Na lista Papel, selecione Projeto > Proprietário.

    Observação: o campo Papel autoriza sua conta de serviço a acessar recursos. É possível visualizar e alterar esse campo mais tarde usando o Console do Cloud. Se você estiver desenvolvendo um aplicativo de produção, especifique permissões mais granulares do que Projeto > Proprietário. Para mais informações, consulte Como atribuir papéis a contas de serviço.
  5. Clique em Criar. O download de um arquivo JSON que contém a chave é feito no computador.

Linha de comando

É possível executar os seguintes comandos usando o SDK do Cloud na máquina local ou no Cloud Shell.

  1. Crie a conta de serviço. Substitua [NAME] por um nome para a conta de serviço.

    gcloud iam service-accounts create [NAME]
  2. Conceda permissões à conta de serviço. Substitua [PROJECT_ID] pelo código do seu projeto.

    gcloud projects add-iam-policy-binding [PROJECT_ID] --member "serviceAccount:[NAME]@[PROJECT_ID].iam.gserviceaccount.com" --role "roles/owner"
    Observação: o campo Papel autoriza a conta de serviço a acessar recursos. Se quiser visualizar e alterar esse campo mais tarde, use o Console do Cloud. Se você estiver desenvolvendo um aplicativo de produção, especifique permissões mais granulares do que Projeto > Proprietário. Para mais informações, consulte Como atribuir papéis a contas de serviço.
  3. Gere o arquivo de chave. Substitua [FILE_NAME] pelo nome do arquivo de chave.

    gcloud iam service-accounts keys create [FILE_NAME].json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

Como fornecer credenciais para um aplicativo

A API Cloud Healthcare pode usar bibliotecas de cliente do Google específicas da linguagem para autenticar aplicativos e fazer chamadas para o Google Cloud. Por exemplo, usando a biblioteca de cliente de APIs do Google para Python, você pode criar um objeto de serviço usando suas credenciais e, em seguida, fazer chamadas para ele.

É possível fornecer credenciais automaticamente ou manualmente. Fornecer credenciais automaticamente é útil ao testar e fazer experimentos, mas pode dificultar a descoberta de quais credenciais seu aplicativo está usando. Como alternativa, forneça as credenciais manualmente.

Como definir as variáveis de ambiente

É possível fornecer credenciais de autenticação ao código ou aos comandos do aplicativo definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS como o caminho do arquivo JSON que contém a chave da conta de serviço.

Se você estiver executando seu aplicativo no Compute Engine, no Google Kubernetes Engine (GKE) ou no App Engine, só precisará definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS se estiver usando uma conta de serviço diferente da conta de serviço padrão que esses serviços fornecem.

Os exemplos a seguir mostram como definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS:

Comando curl

Se você estiver usando curl, execute o comando a seguir. Substitua PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço e FILE_NAME pelo nome de arquivo. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, precisará definir a variável novamente.

export GOOGLE_APPLICATION_CREDENTIALS=PATH/FILE_NAME

Exemplo:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account.json"

PowerShell

Se você estiver usando o Windows PowerShell, execute o comando a seguir. Substitua PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço e FILE_NAME pelo nome de arquivo. Essa variável só se aplica à sessão de shell atual. Dessa maneira, se você abrir uma nova sessão, precisará definir a variável novamente.

$env:GOOGLE_APPLICATION_CREDENTIALS="PATH/FILE_NAME"

Exemplo:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service_account.json"

Depois de definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS, o Application Default Credentials (ADC) pode determinar implicitamente suas credenciais.

Como encontrar credenciais automaticamente

As bibliotecas de cliente da API do Google usam o Application Default Credentials (ADC) para encontrar automaticamente as credenciais do aplicativo.

Quando seu código usa uma biblioteca de cliente, ela verifica suas credenciais na seguinte ordem:

  1. O ADC verifica se a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS está configurada. Se estiver, o ADC usa o arquivo da conta de serviço para o qual variável aponta. Como definir as variáveis de ambiente descreve como definir a variável de ambiente.
  2. Se a variável não estiver configurada, o ADC usará a conta de serviço padrão fornecida pelo Compute Engine, Google Kubernetes Engine (GKE) ou App Engine, se o aplicativo estiver sendo executado em qualquer um desses serviços.

Caso o ADC não use nenhuma das credenciais acima, um erro é gerado.

O exemplo de código a seguir mostra o uso do ADC. A amostra não especifica explicitamente as credenciais do aplicativo. No entanto, o ADC pode encontrar implicitamente as credenciais e armazená-las na variável auth, desde que a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS esteja definida ou enquanto o aplicativo estiver em execução no Compute Engine, GKE ou App Engine.

Node.js

Usa a biblioteca de cliente do Node.js.

const {google} = require('googleapis');
const healthcare = google.healthcare('v1');

const createDataset = async () => {
  const auth = await google.auth.getClient({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  });
  google.options({auth});

  // TODO(developer): uncomment these lines before running the sample
  // const cloudRegion = 'us-central1';
  // const projectId = 'adjective-noun-123';
  // const datasetId = 'my-dataset';
  const parent = `projects/${projectId}/locations/${cloudRegion}`;
  const request = {parent, datasetId};

  await healthcare.projects.locations.datasets.create(request);
  console.log(`Created dataset: ${datasetId}`);
};

createDataset();

Como receber e fornecer credenciais da conta de serviço manualmente

Você pode criar e receber credenciais da conta de serviço manualmente e, em seguida, transmitir as credenciais para o aplicativo no código. Consulte Como receber e fornecer credenciais da conta de serviço manualmente para mais informações.

Autorização de conta de serviço usando JSON Web Tokens (JWTs)

Você pode fazer chamadas autorizadas para a API Cloud Healthcare que não usam o OAuth 2.0. Para fazer isso, use um JSON Web Token (JWT) assinado diretamente como um token do portador, em vez de um token de acesso OAuth 2.0. A API Cloud Healthcare não requer um método específico de geração de tokens. Uma coleção de bibliotecas de cliente auxiliares pode ser encontrada em JWT.io (em inglês). Ao usar um JWT assinado, você pode evitar ter que fazer uma solicitação de rede ao servidor de autorização do Google antes de fazer uma chamada de API.

Ao usar um JWT, especifique https://healthcare.googleapis.com/ no campo aud.

Para autorizar chamadas à API Cloud Healthcare usando um JWT em vez de um token de acesso, siga as instruções em Adendo: autorização de conta de serviço sem OAuth.

O JWT criado deve ser semelhante ao exemplo a seguir:

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "PRIVATE_KEY_ID"
   }
   .
   {
     "iss": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
     "sub": "SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com",
     "aud": "https://healthcare.googleapis.com/",
     "iat": CURRENT_UNIX_TIME,
     "exp": EXPIRATION_TIME
   }
   

A seguir