Usar APIs Datastream

Definir variáveis de ambiente

Neste procedimento, vai definir as seguintes variáveis:

• $PROJECT: esta variável está associada ao seu Google Cloud projeto. Todos os recursos do Google Cloud que atribuir e usar têm de pertencer a um projeto.Google Cloud
• $TOKEN: esta variável está associada a um token de acesso. O token de acesso fornece uma sessão que o Cloud Shell usa para realizar tarefas no Datastream através de APIs REST.

1. Inicie a aplicação Cloud Shell.

2. Depois de se autenticar na sua aplicação com a sua Conta Google, introduza o seguinte comando:

   gcloud auth login
   

3. Na mensagem Do you want to continue (Y/n)?, introduza Y.

4. Abra um navegador de Internet e copie o URL para o navegador.

5. Faça a autenticação no SDK Google Cloud com a sua Conta Google. É apresentado um código na página Início de sessão. Este código é a sua chave de acesso.

6. Copie o token de acesso, cole-o no parâmetro Enter verification code: na sua aplicação Cloud Shell e prima Enter.

7. No comando, introduza PROJECT=\"YOUR_PROJECT_NAME\" para definir a variável de ambiente $PROJECT para o seu projeto Google Cloud.

8. No comando, introduza gcloud config set project YOUR_PROJECT_NAME para definir o projeto no qual quer trabalhar como o seu Google Cloud projeto.

   A linha de comandos é atualizada para refletir o seu projeto ativo e respeita este formato: USERNAME@cloudshell:~ (YOUR_PROJECT_NAME)$

9. No comando, introduza TOKEN=$(gcloud auth print-access-token) para obter o token de acesso e armazená-lo como uma variável.

10. No comando, introduza os seguintes comandos para garantir que as variáveis $PROJECT e $TOKEN estão definidas corretamente:

    • echo $PROJECT
    • echo $TOKEN

Agora que definiu as variáveis, pode fazer pedidos ao Datastream para criar e gerir perfis de associação e uma stream.

Crie e faça a gestão de perfis de associação

Nesta secção, cria e gere perfis de associação para uma base de dados Oracle de origem e um contentor de destino no Cloud Storage.

Quando cria estes perfis de associação, cria registos que contêm informações sobre a base de dados de origem e o contentor do Cloud Storage de destino. O Datastream usa as informações nos perfis de associação para transferir dados da base de dados de origem para uma pasta no contentor de destino.

A criação e a gestão de perfis de associação incluem:

• Criar perfis de associação para uma base de dados Oracle de origem e um contentor de destino no Cloud Storage
• A obter informações sobre um perfil de associação
• Modificar um perfil de associação
• Executar uma chamada API discover no perfil de ligação do Oracle de origem. Esta chamada permite-lhe analisar a base de dados para ver os objetos associados à mesma. Estes objetos incluem os esquemas e as tabelas que contêm os dados da base de dados. Quando usa a stream de dados para configurar uma stream, pode não querer extrair todos os objetos da base de dados, mas sim um subconjunto dos objetos (por exemplo, apenas determinadas tabelas e esquemas da base de dados). Use a API Discover para ajudar a encontrar (ou descobrir) o subconjunto de objetos da base de dados que quer extrair.

Crie perfis de ligação

Neste procedimento, cria dois perfis de ligação: um a uma base de dados Oracle de origem e outro a um contentor de destino no Cloud Storage.

1. Crie um perfil de associação a uma base de dados Oracle de origem. No comando, introduza o seguinte comando:

ORACLE="{\"displayName\":\"DISPLAY_NAME\",\"oracle_profile\":{\"hostname\":\"HOSTNAME\",\"username\":\"USERNAME\",\"password\":\"PASSWORD\",\"database_service\":\"DATABASE_SERVICE\",\"port\":"PORT_NUMBER\"},\"no_connectivity\":{}}"
  

Use a tabela seguinte para ajudar a compreender os valores dos parâmetros da base de dados Oracle de origem:

1. No comando, introduza o comando echo $ORACLE | jq para ver o perfil de ligação de origem que criou em texto fácil de ler.

   {
     "displayName": "DISPLAY_NAME",
     "oracle_profile": {
       "hostname": "HOSTNAME",
       "username": "USERNAME",
       "password": "PASSWORD",
       "database_service": "DATABASE_SERVICE",
       "port": PORT_NUMBER
      },
     "no_connectivity": {}
   }

2. Envie o perfil de ligação do Oracle para que possa ser criado. No comando, introduza o seguinte comando:

   curl -X POST -d $ORACLE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles?connection_profile_id=SOURCE_CONNECTION_PROFILE_ID

   Use a tabela seguinte para ajudar a compreender os valores dos parâmetros para este comando:

   Valor do parâmetro	Substituir por
   DATASTREAM_API_VERSION	A versão atual da API Datastream (por exemplo, v1).
   PROJECT_PATH	O caminho completo do seu Google Cloud projeto (por exemplo, projects/$PROJECT/locations/YOUR_PROJECT_LOCATION).
   SOURCE_CONNECTION_PROFILE_ID	O identificador exclusivo reservado para este perfil de associação (por exemplo, cp-1).

3. Verifique se vê as seguintes linhas de código:

   {
     "name": "PROJECT_PATH/operations/operation-SOURCE_CONNECTION_PROFILE_OPERATION_ID",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
       "createTime": "DATE_AND_TIME_STAMP",
       "target": "datastream.googleapis.com/DATASREAM_VERSION/PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
       "verb": "create",
       "requestedCancellation": false,
       "apiVersion": "DATASTREAM_API_VERSION"
     },
     "done": false
   }

4. Crie um perfil de associação a um contentor de destino no Cloud Storage. No comando, introduza o seguinte comando:

   GOOGLECLOUDSTORAGE="{\"displayName\":\"DISPLAY_NAME\",\"gcs_profile\":{\"bucket_name\":\"BUCKET_NAME\",\"root_path\":\"/FOLDER_PATH\"},\"no_connectivity\":{}}"

   Use a tabela seguinte para ajudar a compreender os valores dos parâmetros do contentor de destino:

   Valor do parâmetro	Substituir por
   DISPLAY_NAME	O nome a apresentar do perfil de associação ao contentor de destino.
   BUCKET_NAME	O nome do contentor de destino.
   FOLDER_PATH	A pasta no contentor de destino para a qual o Datastream transfere dados da base de dados de origem (por exemplo, /root/path).

5. No comando, introduza o comando echo $GOOGLECLOUDSTORAGE | jq para ver o perfil de ligação de destino que criou em texto fácil de ler.

   {
     "displayName": "DISPLAY_NAME",
     "gcs_profile": {
       "bucket_name": "BUCKET_NAME",
       "root_path": "/FOLDER_PATH"
     },
     "no_connectivity": {}
   }

6. Envie o perfil de associação do Cloud Storage para que possa ser criado. No comando, introduza o seguinte comando:

   curl -X POST -d $GOOGLECLOUDSTORAGE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles?connection_profile_id=DESTINATION_CONNECTION_PROFILE_ID

7. Verifique se vê as seguintes linhas de código:

   {
     "name": "PROJECT_PATH/operations/operation-DESTINATION_CONNECTION_PROFILE_OPERATION_ID",
     "metadata": {
       "@type": "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
       "createTime": "DATE_AND_TIME_STAMP",
       "target": "datastream.googleapis.com/DATASTREAM_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
       "verb": "create",
       "requestedCancellation": false,
       "apiVersion": "DATASTREAM_API_VERSION"
     },
     "done": false
   }

8. Confirme se ambos os perfis de ligação foram criados. No comando, introduza o seguinte comando:

   curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles

9. Confirme se recebe dois resultados devolvidos para os perfis de ligação de origem e de destino.

   {
     "connectionProfiles": [
       {
         "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
         "createTime": "DATE_AND_TIME_STAMP",
         "updateTime": "DATE_AND_TIME_STAMP",
         "displayName": "DISPLAY_NAME",
         "gcsProfile": {
           "bucketName": "BUCKET_NAME",
           "rootPath": "FOLDER_PATH"
         },
         "noConnectivity": {}
       },
      {
       "name": "PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
       "createTime": "DATE_AND_TIME_STAMP",
       "updateTime": "DATE_AND_TIME_STAMP",
       "displayName": "DISPLAY_NAME",
       "oracleProfile": {
         "hostname": "HOSTNAME",
         "port": PORT_NUMBER,
         "username": "USERNAME",
         "databaseService": "DATABASE_SERVICE"
       },
       "noConnectivity": {}
       }
     ]
   }

Faça a gestão dos perfis de ligação

Neste procedimento, gere os perfis de ligação que criou para uma base de dados Oracle de origem e um contentor de destino no Cloud Storage. Isto inclui:

• Obter informações sobre o perfil de ligação do Cloud Storage de destino
• Modificar este perfil de associação. Para este tutorial, vai alterar a pasta do contentor do Cloud Storage de destino para /root/tutorial. O stream de dados transfere dados da base de dados de origem para esta pasta.
• Executar uma chamada API discover no perfil de ligação do Oracle de origem

1. Obter informações sobre o perfil de ligação do Cloud Storage de destino. No comando, introduza o seguinte comando:

   curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID

2. Confirme que vê informações sobre este perfil de associação.

   {
     "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
     "createTime": "DATE_AND_TIME_STAMP",
     "updateTime": "DATE_AND_TIME_STAMP",
     "displayName": "DISPLAY_NAME",
     "gcsProfile": {
       "bucketName": "BUCKET_NAME",
       "rootPath": "FOLDER_PATH"
     },
     "noConnectivity": {}
   }

3. Modifique este perfil de associação. Para tal, primeiro, defina uma variável UPDATE. Esta variável contém os valores do perfil de associação que quer alterar. Para este tutorial, vai alterar a pasta do contentor de destino para /root/tutorial.

   Para definir a variável, na linha de comandos, introduza o seguinte comando:

   UPDATE="{\"gcsProfile\":{\"rootPath\":\"/root/tutorial\"}}"

4. No comando, introduza o seguinte comando:

   curl -X PATCH -d $UPDATE -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID?update_mask=gcsProfile.rootPath

5. Verifique se vê as seguintes linhas de código:

   {
     "name": "PROJECT_PATH/operations/operation-DESTINATION_CONNECTION_PROFILE_OPERATION_ID",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.datastream.DATASTREAM_API_VERSION.OperationMetadata",
       "createTime": "DATE_AND_TIME_STAMP",
       "target": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
       "verb": "update",
       "requestedCancellation": false,
       "apiVersion": "DATASTREAM_API_VERSION"
     },
     "done": false
   }

6. Confirme que o perfil de ligação é modificado. No comando, introduza o seguinte comando:

   curl -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID

7. Verifique se a pasta do contentor de destino do perfil de ligação do Cloud Storage é agora /root/tutorial.

   {
     "name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
     "createTime": "DATE_AND_TIME_STAMP",
     "updateTime": "DATE_AND_TIME_STAMP",
     "displayName": "DISPLAY_NAME",
     "gcsProfile": {
       "bucketName": "BUCKET_NAME",
       "rootPath": "/root/tutorial"
     },
     "noConnectivity": {}
   }

8. Use a API Datastream Discover para descobrir os esquemas e as tabelas da base de dados Oracle de origem. O fluxo de dados fornece acesso a esta base de dados através do perfil de associação de origem.

   1. Descubra os esquemas da base de dados Oracle. No comando, introduza o seguinte comando:

      curl -X POST -d "{\"connection_profile_name\":\"projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID\", \"oracle_rdbms\":{\"oracleSchemas\":[{\"schema\":\"ROOT\"}]}}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles:discover

   2. Verifique se o Datastream obtém todos os esquemas da sua base de dados.

   3. Obtenha as tabelas de um esquema na sua base de dados. Para este tutorial, vai usar a API Discover para obter as tabelas do esquema ROOT. No entanto, pode descobrir as tabelas de qualquer esquema na sua base de dados.

      No comando, introduza o seguinte comando:

   curl -X POST -d "{\"connection_profile_name\":\"projects/YOUR_PROJECT_NUMBER/locations/YOUR_PROJECT_LOCATION/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID\", \"oracle_rdbms\":{\"oracleSchemas\":[{\"schema\":\"ROOT\"}]}}" -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" https://datastream.googleapis.com/DATASTREAM_API_VERSION/PROJECT_PATH/connectionProfiles:discover

   1. Verifique se o fluxo de dados obtém todas as tabelas do esquema que especificou (para este tutorial, o esquema ROOT).

Agora que criou e geriu perfis de associação para uma base de dados Oracle de origem e um contentor de destino no Cloud Storage, está pronto para criar e gerir uma stream no Datastream.

Criar e gerir uma stream

Nesta secção, cria e gere uma stream. O Datastream usa esta stream para transferir dados, esquemas e tabelas da base de dados de origem para uma pasta no contentor do Cloud Storage de destino.

A criação e a gestão de uma stream incluem:

• Validar uma stream para garantir que é executada com êxito e que todas as verificações de validação são aprovadas. Estas verificações incluem:
  • Se a origem está configurada corretamente para permitir que o fluxo de dados transmita dados a partir da mesma.
  • Se a stream consegue estabelecer ligação à origem e ao destino.
  • A configuração ponto a ponto da stream.
• A criar a stream com as seguintes listas:
  • Uma lista de autorizações. Esta lista especifica as tabelas e os esquemas na base de dados de origem que o Datastream pode transferir para uma pasta no contentor de destino no Cloud Storage. Para este tutorial, esta é a pasta /root/tutorial.
  • Uma lista de rejeição. Esta lista especifica as tabelas e os esquemas na base de dados de origem cuja transferência para a pasta no contentor de destino do Cloud Storage está restrita ao Datastream.
• A obter informações sobre a stream
• Modificar a stream
• Iniciar a stream para que o Datastream possa transferir dados, esquemas e tabelas da base de dados de origem para uma pasta no contentor do Cloud Storage de destino.
• Usar a API Fetch Errors para detetar erros associados à stream
• Pausar a stream. Quando uma stream é pausada, o Datastream não extrai novos dados da base de dados de origem para o contentor de destino.
• Retomar a stream pausada para que a stream de dados possa continuar a transferir dados para o contentor de destino.

Crie uma stream

Neste procedimento, cria uma stream a partir da base de dados Oracle de origem para uma pasta no contentor do Cloud Storage de destino. A stream que criar inclui uma lista de autorizações e uma lista de rejeições.

1. Defina uma variável SCHEMAS. Esta variável define os esquemas que contêm os dados e as tabelas que quer que o Datastream obtenha da base de dados de origem e transfira para a pasta /root/tutorial do contentor de destino do Cloud Storage. Para este tutorial, vai definir a variável SCHEMAS para ser associada ao esquema ROOT.

   No comando, introduza o seguinte comando:

   SCHEMAS="{\"oracleSchemas\":[{\"schema\":\"ROOT\"}]}"

2. No comando, introduza o comando echo $SCHEMAS | jq para ver o esquema ROOT que definiu para esta variável num texto fácil de ler.

3. Crie uma stream. No comando, introduza o seguinte comando:

   STREAM="{\"display_name\":\"DISPLAY_NAME\",\"source_config\":{\"source_connection_profile_name\":\"PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",\"oracle_source_config\":{\"allowlist\":$SCHEMAS,\"rejectlist\":{}}},\"destination_config\":{\"destination_connection_profile_name\":\"PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID\",\"gcs_destination_config\":{\"file_rotation_mb\":5,\"file_rotation_interval\":{\"seconds\":15},\"avro_file_format\":{}},\"backfill_all\":{}}}"

4. No comando, introduza o comando echo $STREAM | jq para ver a stream que criou em texto fácil de ler.

   {
     "display_name": "DISPLAY_NAME",
     "source_config": {
       "source_connection_profile_name": "PROJECT_PATH/connectionProfiles/SOURCE_CONNECTION_PROFILE_ID",
       "oracle_source_config": {
         "allowlist": {
           "oracleSchemas": [
             {
               "schema": "ROOT"
             }
           ]
         },
         "rejectlist": {}
       }
     },
     "destination_config": {
       "destination_connection_profile_name": "PROJECT_PATH/connectionProfiles/DESTINATION_CONNECTION_PROFILE_ID",
       "gcs_destination_config": {
         "file_rotation_mb": 5,
         "file_rotation_interval": {
           "seconds": 15
         },
         "avro_file_format": {}
       }
     },
     "backfill_all": {}
   }

   Use esta tabela para ajudar a compreender os seguintes parâmetros da stream:

   Parâmetro	Descrição
   allowlist	Os esquemas, que contêm tabelas e dados, que vão ser transferidos da base de dados de origem para uma pasta do contentor de destino do Cloud Storage. Para este tutorial, todas as tabelas e dados do esquema ROOT (e apenas deste esquema) vão ser transferidos para a pasta /root/tutorial do contentor de destino.
   rejectlist	Todos os esquemas, que contêm tabelas e dados, que não são transferidos para uma pasta do contentor de destino do Cloud Storage. Para este tutorial, o valor