Usar a API Datastream

Informações gerais

O Datastream oferece uma API REST para administrar configurações de conectividade particular, perfis de conexão e streams de maneira programática. A API REST é definida por recursos associados à criação e ao gerenciamento de configurações de conectividade particular, perfis de conexão e streams. Para detalhes sobre todos os recursos e os respectivos métodos, consulte a Referência da API Datastream.

Ao enviar solicitações diretamente para a API REST do Datastream, você precisa criar a forma correta da solicitação, autorizá-la como um usuário autenticado e processar as respostas retornadas. Muitas das tarefas nesta documentação fornecem exemplos de API usando cURL.

Para mais exemplos de como usar as APIs, consulte a página da solicitação na Referência da API Datastream. Cada página tem exemplos de chamada da API em várias linguagens de programação, bem como um explorador específico da solicitação para ajudar você a ver o que entra em uma solicitação bem formada e o que esperar na resposta.

Você também está usando a API Datastream, indiretamente, quando usa uma das seguintes maneiras de administrar instâncias:

Google Cloud CLI: uma interface de linha de comando (CLI) que você pode usar para trabalhar com instâncias.
Console do Google Cloud: uma interface gráfica da Web.

A vantagem de usar esses métodos, especialmente o Console do Google Cloud, é que eles podem simplificar muito a administração de configurações de conectividade particular, perfis de conexão e streams (dependendo do caso de uso). Se você está apenas começando com o Datastream, recomendamos que comece com uma dessas ferramentas antes de trabalhar diretamente com a API REST.

Ativar a API

Para usar a API Datastream, é necessário ativá-la:

Console

Ative a API Datastream.
Selecione o projeto.
Selecione Continuar.

gcloud

Insira o comando abaixo para exibir os IDs dos seus projetos do Google Cloud:
```
gcloud projects list
```

Defina o projeto padrão:

gcloud config set project YOUR_PROJECT_ID

Ative a API Datastream:

gcloud services enable datastream.googleapis.com

Permissões

Você precisa ter as permissões necessárias para usar a API Datastream. Essas permissões incluem:

Administrador do Datastream: com essa permissão, um usuário tem acesso a todos os recursos do Datastream usados para gerenciar configurações de conectividade particular, perfis de conexão e streams.
Visualizador do Datastream: com esta permissão, um usuário tem acesso somente leitura a configurações de conectividade particular, perfis de conexão e streams no Datastream.

O Google Cloud oferece o gerenciamento de identidade e acesso (IAM), que permite a concessão de acesso mais granular a recursos específicos do Google Cloud e impede o acesso indesejado a outros recursos. É possível receber e definir permissões para o Datastream usando o Console do Google Cloud, os métodos do IAM da API ou o SDK do Google Cloud. Saiba mais em Como conceder, alterar e revogar acesso a recursos.

Exemplos de API

Veja exemplos de como usar a API Datastream com cURL nas seguintes páginas da documentação do Datastream:

Fornecer dados JSON de um arquivo

Ao usar a API com cURL, você fornece valores de propriedade usando a linha de comando. Se você estiver trabalhando com valores confidenciais, como senhas ou chaves de segurança, fornecê-los na linha de comando representa um risco de segurança. Para aumentar a segurança, você pode criar um arquivo contendo os dados JSON para a chamada de API e fornecer o caminho para o arquivo na linha de comando.

Para fornecer dados JSON à chamada de API cURL a partir de um arquivo:

Crie um arquivo contendo tudo entre aspas simples para o campo --data.

Coloque as chaves, mas não use aspas simples.

Na linha de comando, forneça o caminho para o arquivo, precedido pelo caractere @, como o parâmetro --data:

--data @<path-to-file>/<filename>

Por exemplo, para criar um perfil de conexão para uma origem MySQL, crie um arquivo chamado request.json com o seguinte conteúdo:

{
  "displayName": "my MySQL connection profile",
  "mysql": {
    "host": "10.11.12.13",
    "port": 3306,
    "username": "myusername",
    "password": "mypassword"
  }
}

Em seguida, você usaria o seguinte comando cURL na linha de comando:

curl --header "Authorization: Bearer ${ACCESS_TOKEN}" \
     --header 'Content-Type: application/json' \
     --data @./request.json \
     -X POST \
     https://datastream.googleapis.com/v1/projects/myProject/locations/myLocation/connectionProfiles?connectionProfileId=myMySQLconnectionprofile

Trabalhar com chamadas de API de longa duração

Algumas chamadas de API, como a criação de objetos, podem levar algum tempo para serem concluídas. Como a API é assíncrona, a chamada é retornada imediatamente, mesmo que a operação ainda esteja em andamento. Se uma chamada de API subsequente usar o objeto recém-criado, aguarde a conclusão da primeira operação antes de continuar.

É possível usar a API Datastream para gerenciar operações. Incluindo:

Datastream e o serviço de descoberta de APIs do Google

O Serviço de descoberta de APIs do Google é um serviço que você pode usar para descobrir APIs do Google. Por exemplo, quando usar a ferramenta APIs Explorer do Google , você estará usando o serviço de descoberta.

No Discovery Service, o Datastream é representado como "datastream" (por exemplo: https://datastream.googleapis.com/$discovery/rest?version=v1).