Como autenticar com a 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

Crie uma conta de serviço:

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

    Acesse Criar conta de serviço
  2. Selecione um projeto.
  3. No campo Nome da conta de serviço, insira um nome. O Console do Cloud preenche o campo ID da conta de serviço com base nesse nome.

    No campo Descrição da conta de serviço, insira uma descrição. Por exemplo, Service account for quickstart.

  4. Clique em Criar e continuar.
  5. Clique no campo Selecionar um papel.

    Em Acesso rápido, clique em Básico e em Proprietário.

  6. Clique em Continuar.
  7. Clique em Concluído para terminar a criação da conta de serviço.

    Não feche a janela do navegador. Você vai usá-lo na próxima etapa.

Crie uma chave de conta de serviço:

  1. No Console do Cloud, clique no endereço de e-mail da conta de serviço que você criou.
  2. Clique em Chaves.
  3. Clique em Adicionar chave e em Criar nova chave.
  4. Clique em Criar. O download de um arquivo de chave JSON é feito no seu computador.
  5. Clique em Fechar.

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 ID do seu projeto.

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role="roles/owner"
  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:

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/healthcare');
const healthcare = google.healthcare({
  version: 'v1',
  auth: new google.auth.GoogleAuth({
    scopes: ['https://www.googleapis.com/auth/cloud-platform'],
  }),
});

const createDataset = async () => {
  // 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