Amazon S3
O conector do Amazon S3 oferece acesso SQL a buckets e objetos do Amazon S3.
Antes de começar
Antes de usar o conector do Amazon S3, faça o seguinte:
- No seu projeto do Google Cloud, faça o seguinte:
- Verifique se a conectividade de rede está configurada. Para informações sobre padrões de rede, consulte Conectividade de rede.
- Conceda o papel do IAM roles/connectors.admin ao usuário que está configurando o conector.
- Conceda os seguintes papéis de IAM à conta de serviço que você quer usar para o conector:
roles/secretmanager.viewer
roles/secretmanager.secretAccessor
Uma conta de serviço é um tipo especial de Conta do Google destinada a representar um usuário não humano que precisa ser autenticado e autorizado a acessar dados nas APIs do Google. Se você não tiver uma conta de serviço, será necessário criar uma. Para mais informações, consulte Como criar uma conta de serviço.
- Ative os seguintes serviços:
secretmanager.googleapis.com
(API Secret Manager)connectors.googleapis.com
(API Connectors)
Para entender como ativar os serviços, consulte Como ativar serviços.
Se esses serviços ou permissões não tiverem sido ativados no seu projeto, você precisará ativá-los ao configurar o conector.
Configurar o conector
Uma conexão é específica a uma fonte de dados. Isso significa que, se você tiver muitas fontes de dados, precisará criar uma conexão separada para cada uma. Para criar uma conexão, faça o seguinte:
- No console do Cloud, acesse a página Integration Connectors > Conexões e selecione ou crie um projeto do Google Cloud.
- Clique em + Criar novo para abrir a página Criar conexão.
- Na seção Local, escolha o local da conexão.
- Região: selecione um local na lista suspensa.
Veja abaixo as regiões compatíveis com o conector:
Para conferir a lista de todas as regiões com suporte, consulte Locais.
- Clique em Próxima.
- Região: selecione um local na lista suspensa.
- Na seção Detalhes da conexão, faça o seguinte:
- Conector: selecione Amazon S3 na lista suspensa de conectores disponíveis.
- Versão do conector: selecione a versão do conector na lista suspensa de versões disponíveis.
- No campo Nome da conexão, insira um nome para a instância de conexão
Os nomes de conexão precisam atender aos seguintes critérios:
- Os nomes de conexões podem usar letras, números ou hifens.
- As letras precisam ser minúsculas.
- Os nomes das conexões precisam começar com uma letra e terminar com uma letra ou um número.
- Os nomes das conexões não podem exceder 49 caracteres.
- Como opção, insira uma Descrição para a instância de conexão.
- Se quiser, ative o Cloud Logging e selecione um nível de registro. Por padrão, o nível de registro é definido como
Error
. - Conta de serviço: selecione uma conta de serviço que tenha os papéis necessários.
- Opcionalmente, defina as Configurações do nó de conexão:
- Número mínimo de nós: digite o número mínimo de nós de conexão.
- Número máximo de nós: digite o número máximo de nós de conexão.
Um nó é uma unidade (ou réplica) de uma conexão que processa transações. Mais nós são necessários para processar mais transações para uma conexão e, por outro lado, menos nós são necessários para processar menos transações. Para entender como os nós afetam os preços do conector, consulte Preços dos nós de conexão. Se você não inserir qualquer valor, por padrão, os nós mínimos serão definidos como 2 (para melhor disponibilidade) e os nós máximos serão definidos como 50.
- Região da AWS: região em que a instância do Amazon S3 está hospedada
- Outra opção é clicar em + Adicionar rótulo para adicionar um rótulo à conexão na forma de um par de chave-valor.
- Clique em Próxima.
- Na seção Destinos, insira os detalhes do host remoto (sistema de back-end) ao qual você quer se conectar.
- Tipo de destino: selecione um Tipo de destino.
- Para especificar o nome do host ou o endereço IP de destino, selecione Endereço do host e insira o endereço no campo Host 1.
- Para estabelecer uma conexão particular, selecione Anexo de endpoint e escolha o anexo necessário na lista Anexo de endpoint.
Para estabelecer uma conexão pública com os sistemas de back-end com mais segurança, considere configurar endereços IP de saída estáticos para suas conexões e configure as regras de firewall para autorizar apenas os endereços IP estáticos específicos.
Para inserir outros destinos, clique em + Adicionar destino.
- Clique em Próxima.
- Tipo de destino: selecione um Tipo de destino.
-
Na seção Autenticação, insira os detalhes da autenticação.
- Selecione um Tipo de autenticação e insira os detalhes relevantes.
A conexão do Amazon S3 aceita os seguintes tipos de autenticação:
- Credenciais raiz
- Papéis do IAM da AWS
- Credenciais temporárias da AWS
- Clique em Next.
Para entender como configurar esses tipos de autenticação, consulte Configurar autenticação.
- Selecione um Tipo de autenticação e insira os detalhes relevantes.
- Revisão: revise os detalhes de conexão e autenticação.
- Clique em Criar.
Configurar a autenticação
Digite os detalhes com base na autenticação que você quer usar.
-
Credenciais raiz
Para autenticar usando credenciais da raiz da conta.
- Chave de acesso da AWS: a chave de acesso do usuário raiz
- AWS Access Secret: a chave secreta do usuário raiz
-
Papéis do IAM da AWS
Para autenticar usando um papel do IAM da AWS.
- Chave de acesso da AWS: a chave de acesso do usuário do IAM para assumir a função de
- AWS Access Secret: a chave secreta do usuário do IAM para assumir a função de
- ARN do papel da AWS: especifique o ARN do papel com que você quer se autenticar. Somente as credenciais da função especificada seriam recuperadas.
- ID externo da AWS: obrigatório apenas quando você assume uma função em outra conta.
-
Credenciais temporárias da AWS
Para autenticar usando credenciais temporárias
- Chave de acesso da AWS: a chave de acesso do usuário do IAM para assumir a função de
- AWS Access Secret: a chave secreta do usuário do IAM para assumir a função de
- Token de sessão da AWS: gerado junto com as credenciais temporárias.
- ARN do papel da AWS: especifique o ARN do papel com que você quer se autenticar. Somente as credenciais da função especificada seriam recuperadas.
- ID externo da AWS: obrigatório apenas quando você assume uma função em outra conta.
Para saber como configurar uma conta da AWS, consulte Configurar o Amazon S3. Para informações sobre como criar um bucket do S3, consulte Criar um bucket do S3. Entre em contato com o administrador da AWS para criar credenciais de função do IAM ou temporárias na conta da AWS.
Exemplos de configuração de conexão
Esta seção lista os valores de amostra para os vários campos que você configura ao criar a conexão do Amazon S3.
Tipo de conexão de credenciais raiz
Nome do campo | Detalhes |
---|---|
Local | europe-west1 |
Conector | Amazon S3 |
Versão do conector | 1 |
Nome da conexão | aws-s3 |
Descrição | aws-s3 |
Conta de serviço | SERVICE_ACCOUNT_NAME@serviceaccount |
Região da AWS | Norte da Virgínia |
Número mínimo de nós | 2 |
Número máximo de nós | 50 |
Credenciais raiz | Sim |
Chave de acesso da AWS | AWS_ACCESS_KEY |
Secret de acesso da AWS | AWS_ACCESS_SECRET |
Versão do secret | 1 |
Tipo de conexão de papéis do IAM da AWS
Nome do campo | Detalhes |
---|---|
Local | europe-west1 |
Conector | Amazon S3 |
Versão do conector | 1 |
Nome da conexão | aws-s3 |
Descrição | aws-s3 |
Conta de serviço | SERVICE_ACCOUNT_NAME@serviceaccount |
Região da AWS | Norte da Virgínia |
Número mínimo de nós | 2 |
Número máximo de nós | 50 |
Papéis do IAM da AWS | Sim |
Chave de acesso da AWS | AWS_ACCESS_KEY |
Secret de acesso da AWS | AWS_ACCESS_SECRET |
Versão do secret | 1 |
Tipo de conexão de credenciais temporárias da AWS
Nome do campo | Detalhes |
---|---|
Local | europe-west1 |
Conector | Amazon S3 |
Versão do conector | 1 |
Nome da conexão | aws-s3 |
Descrição | aws-s3 |
Conta de serviço | SERVICE_ACCOUNT_NAME@serviceaccount |
Região da AWS | Norte da Virgínia |
Número mínimo de nós | 2 |
Número máximo de nós | 50 |
Credenciais temporárias da AWS | Sim |
Chave de acesso da AWS | AWS_ACCESS_KEY |
Secret de acesso da AWS | AWS_ACCESS_SECRET |
Versão do secret | 1 |
Token de sessão da AWS | AWS_SESSION_TOKEN |
Entidades, operações e ações
Todos os Integration Connectors fornecem uma camada de abstração para os objetos do aplicativo conectado. Só é possível acessar os objetos de um aplicativo por esta abstração. A abstração é exposta a você como entidades, operações e ações.
- Entidade: uma entidade pode ser considerada um objeto ou um conjunto de propriedades no aplicativo ou serviço conectado. A definição de uma entidade difere de um conector para
outro. Por exemplo, em um conector de banco de dados, as tabelas são as entidades, em um conector de servidor de arquivos, as pastas são as entidades e, em um conector de sistema de mensagens, as filas são as entidades.
No entanto, é possível que um conector não aceite ou não tenha entidades. Nesse caso, a lista
Entities
estará vazia. - Operação: uma operação é a atividade que pode ser realizada em uma entidade. É possível executar
qualquer uma das seguintes operações em uma entidade:
Selecionar uma entidade na lista disponível gera uma lista de operações disponíveis para ela. Para uma descrição detalhada das operações, consulte as operações de entidades da tarefa "Conectores". No entanto, se um conector não oferecer suporte a nenhuma das operações de entidade, essas operações não serão listadas na lista
Operations
. - Ação: uma ação é uma função de primeira classe disponibilizada para a integração por meio da interface do conector. Uma ação permite fazer alterações em uma ou mais entidades e varia de um conector para outro. Normalmente, uma ação tem alguns parâmetros de entrada e um parâmetro de saída. No entanto, é possível que o conector não ofereça suporte a nenhuma ação. Nesse caso, a lista
Actions
estará vazia.
Ações
Esta seção lista algumas das ações compatíveis com o conector. Para entender como configurar as ações, consulte Exemplos de ações.
Ação CopyObject
Com essa ação, é possível copiar um objeto de um bucket para outro ou dentro do mesmo bucket.
Parâmetros de entrada da ação CopyObject
Nome do parâmetro | Tipo de dados | Obrigatório | Descrição |
---|---|---|---|
BucketSource | String | Sim | Nome do bucket de onde o objeto deve ser copiado. |
ObjectSource | Objeto | Sim | Nome do objeto que deve ser copiado. |
BucketDestination | String | Sim | Nome do bucket em que o objeto será copiado. |
ObjectDestination | String | Não | Nome do objeto no bucket de destino. Se não for especificado, o nome será o mesmo que o original. |
Parâmetros de saída da ação CopyObject
Essa ação retorna o status 200 (OK) se a cópia for bem-sucedida.
Para entender como configurar a ação CopyObject
,
consulte Exemplos de ações.
Ação DownloadObjects
Essa ação recebe mais um objeto de um bucket.
Parâmetros de entrada da ação DownloadObjects
Nome do parâmetro | Tipo de dados | Obrigatório | Descrição |
---|---|---|---|
Bucket | String | Sim | Nome do bucket em que o objeto para download está presente. |
Objeto | String | Não | Nome do objeto que deve ser transferido por download. Se não for especificado, todos os objetos do bucket especificado serão baixados. |
HasBytes | Booleano | Sim | Especifica se o conteúdo deve ser baixado como uma string codificada em Base64. |
UpdatedStartDate | Data/hora | Não | A data de início do período para fazer o download de objetos. Se não for especificado, os objetos serão baixados do mais antigo até o UpdatedEndDate. |
UpdatedEndDate | Data/hora | Não | A data de término do período para fazer o download de objetos. Se não for especificado, o download de objetos será feito do UpdatedStartDate especificado até o dia atual. |
Parâmetros de saída da ação DownloadObjects
Essa ação retorna o status 200 (OK) se o download for bem-sucedido.
Para entender como configurar a ação DownloadObjects
,
consulte Exemplos de ações.
Ação UploadObject
Com essa ação, é possível fazer upload de um objeto para um bucket.
Parâmetros de entrada da ação UploadObject
Nome do parâmetro | Tipo de dados | Obrigatório | Descrição |
---|---|---|---|
Bucket | String | Sim | Nome do bucket em que o objeto será enviado. |
ContentBytes | String | Não | O conteúdo de bytes a ser enviado como um arquivo. |
HasBytes | Booleano | Sim | Especifica se o conteúdo precisa ser enviado como uma string codificada em Base64. |
AccessPolicy | String | Não | A política de acesso para este objeto. Os valores permitidos são PRIVATE, ANONREAD, ANONREADWRITE e AUTHREAD. O valor padrão é "PRIVADO". |
Conteúdo | String | Não | O conteúdo a ser enviado. |
FileName | String | Não | Nome do arquivo a ser enviado. Esse valor é obrigatório quando você especifica o parâmetro "FileContent". |
Parâmetros de saída da ação UploadObject
Essa ação retorna o status 200 (OK) se o upload do objeto for bem-sucedido.
Para entender como configurar a ação UploadObject
,
consulte Exemplos de ações.
Ação DeleteObject
Essa ação permite excluir um objeto de um bucket.
Parâmetros de entrada da ação DeleteObject
Nome do parâmetro | Tipo de dados | Obrigatório | Descrição |
---|---|---|---|
Bucket | String | Sim | Nome do bucket em que o objeto a ser excluído está presente. |
Objeto | String | Sim | Nome do objeto que deve ser excluído. |
Parâmetros de saída da ação DeleteObject
Essa ação retorna o status 200 (OK) se a exclusão for bem-sucedida.
Para entender como configurar a ação DeleteObject
,
consulte Exemplos de ações.
Ação MoveObject
Essa ação permite que os usuários movam um objeto de um bucket específico para outro ou para o mesmo bucket.
Parâmetros de entrada da ação MoveObject
Nome do parâmetro | Tipo de dados | Obrigatório | Descrição |
---|---|---|---|
BucketSource | String | Sim | O nome do bucket de origem em que o objeto a ser movido está presente. |
ObjectSource | String | Sim | Nome do objeto que deve ser movido. |
BucketDestination | String | Sim | O nome do bucket de destino para onde o objeto deve ser movido. |
ObjectDestination | String | Não | Nome do objeto no bucket de destino. Se não for especificado, o nome original será mantido. |
Parâmetros de saída da ação MoveObject
Essa ação retorna o status 200 (OK) se a operação de movimentação for bem-sucedida.
Para entender como configurar a ação MoveObject
,
consulte Exemplos de ações.
Ação PutBucketAcl
Com essa ação, é possível atualizar a lista de controle de acesso (ACL) de um bucket.
Parâmetros de entrada da ação PutBucketAcl
Nome do parâmetro | Tipo de dados | Obrigatório | Descrição |
---|---|---|---|
Bucket | String | Sim | Nome do bucket a que a ACL será aplicada. |
ACL | String | Sim | Nível de acesso a ser aplicado ao bucket. |
Parâmetros de saída da ação PutBucketAcl
Essa ação retorna o status 200 (OK) se a atualização da ACL do bucket for bem-sucedida.
Para entender como configurar a ação PutBucketAcl
,
consulte Exemplos de ações.
Ação PutObjectAcl
Essa ação permite atualizar a lista de controle de acesso (ACL) de um objeto em um bucket.
Parâmetros de entrada da ação PutObjectAcl
Nome do parâmetro | Tipo de dados | Obrigatório | Descrição |
---|---|---|---|
Bucket | String | Sim | Nome do bucket em que o objeto está presente. |
ACL | String | Sim | Nível de acesso a ser aplicado ao objeto. |
CHAVE | String | Sim | Nome do objeto a que a ACL deve ser aplicada. |
Parâmetros de saída da ação PutObjectAcl
Essa ação retorna o status 200 (OK) se a atualização da ACL do objeto for bem-sucedida.
Para entender como configurar a ação PutObjectAcl
,
consulte Exemplos de ações.
Exemplos de ações
Nesta seção, descrevemos como executar algumas das ações neste conector.
Exemplo: copiar um objeto
Este exemplo copia um objeto de um bucket para outro.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
CopyObject
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "BucketSource": "aws-s3-bucket-source", "ObjectSource": "pic.jpg", "BucketDestination": "aws-s3-bucket-destination", "ObjectDestination": "new_pic.jpg" }
Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload
da
tarefa CopyObject
terá um valor semelhante a este:
[{ "Status": "Success" }]
Exemplo: fazer o download de um objeto
Este exemplo faz o download de um objeto do bucket especificado.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
DownloadObjects
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "Bucket": "aws-s3-bucket-source", "HasBytes": true }
Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload
da
tarefa DownloadObjects
terá um valor semelhante a este:
[{ "Success": "True", "RemoteFile": "prefix1%2Faws-s3-bucket-source%2Finventory-test-1%2F2023-09-10T01-00Z%2Fmanifest.json", "ContentBytes": "ewogICJzb3VyY2VCdWNrZXQiIDogImF3cy1zMy1idWNrZXQtYmNvbmUiLAogICJnOK" }, { "Success": "True", "RemoteFile": "upload1.txt", "ContentBytes": "VGhpcyBpcyBhIHRlc3RpbmcgZmlsZQ==" }]
Exemplo: fazer upload de um objeto
Este exemplo faz upload de um objeto para o bucket especificado.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
UploadObject
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "Bucket": "aws-s3-bucket-source", "FileName": "upload_1.txt", "Content": "This is a testing file", "AccessPolicy": "PUBLIC" }
Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload
da
tarefa UploadObject
terá um valor semelhante a este:
[{ "Status": "success", "bucket": "aws-s3-bucket-source", "rss:title": "Object 'upload_1.txt' was created in the bucket: aws-s3-bucket-source", "object": "upload_1.txt" }]
Exemplo: excluir um objeto
Este exemplo exclui um objeto do bucket especificado.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
DeleteObject
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "Bucket": "aws-s3-bucket-source", "Object": "abc.png" }
Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload
da
tarefa DeleteObject
terá um valor semelhante a este:
[{ "Status": "Success" }]
Exemplo: mover um objeto
Este exemplo move um objeto de um bucket para outro.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
MoveObject
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "BucketSource": "aws-s3-bucket-source", "ObjectSource": "abc.png", "BucketDestination": "aws-s3-bucket-destination", "ObjectDestination": "moved.png" }
Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload
da
tarefa MoveObject
terá um valor semelhante a este:
[{ "Status": "Success" }]
Exemplo: atualizar a ACL de um bucket
Este exemplo atualiza as permissões de controle de acesso de um bucket.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
PutBucketAcl
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "BucketSource": "aws-s3-bucket-source", "ACL": "public-read" }
Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload
da
tarefa PutBucketAcl
terá um valor semelhante a este:
[{ "Status": "Success" }]
Exemplo: atualizar a ACL de um objeto
Este exemplo atualiza as permissões de controle de acesso de um objeto em um bucket.
- Na caixa de diálogo
Configure connector task
, clique emActions
. - Selecione a ação
PutObjectAcl
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "Bucket": "aws-s3-bucket-source", "ACL": "aws-exec-read", "Key": "AWS_S3_BusinessCase_V2.xlsx" }
Se a ação for bem-sucedida, o parâmetro de resposta connectorOutputPayload
da
tarefa PutObjectAcl
terá um valor semelhante a este:
[{ "Status": "Success" }]
Exemplos de operações de entidade
Nesta seção, mostramos como realizar algumas das operações de entidade neste conector.
Exemplo: listar metadados de todos os objetos
Este exemplo busca os metadados de todos os objetos na entidade Object
.
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione
Object
na listaEntity
. - Selecione a operação
List
e clique em Concluído. - Se quiser, na seção Entrada de tarefa da tarefa Conectores, é possível
filtrar o conjunto de resultados especificando uma cláusula de filtro.
Sempre especifique o valor da cláusula de filtro entre aspas simples ('). Por exemplo,
Bucket='test-bucket'
. Também é possível especificar várias condições de filtro usando os operadores lógicos. Por exemplo,Bucket='test-bucket' and OwnerId='b1ecc809ad8467088afb'
.
Exemplo: receber metadados de um bucket
Este exemplo recebe os metadados do bucket com o ID especificado da entidade Bucket
.
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione
Bucket
na listaEntity
. - Selecione a operação
Get
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Conectores, clique em EntityId e
insira
demo_replication
no campo Valor padrão.Aqui,
demo_replication
é um ID do bucket exclusivo na entidadeBucket
.
Exemplo: criar um bucket
Este exemplo cria um bucket na entidade Bucket
.
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione
Bucket
na listaEntity
. - Selecione a operação
Create
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Connectors, clique em
connectorInputPayload
e insira um valor semelhante ao seguinte no campoDefault Value
:{ "Bucket": "Demo1697528098686" }
Se a integração for bem-sucedida, o campo
connectorOutputPayload
da tarefa do conector terá um valor semelhante a este:[{ "Bucket": "Demo1697528098686" }]
Exemplo: excluir um bucket
Este exemplo exclui o bucket com o ID especificado na entidade Bucket
.
- Na caixa de diálogo
Configure connector task
, clique emEntities
. - Selecione
Bucket
na listaEntity
. - Selecione a operação
Delete
e clique em Concluído. - Na seção Entrada da tarefa da tarefa Conectores, clique em entityId e
insira
demo1697528098686
no campo Valor padrão.
Usar a conexão do Amazon S3 em uma integração
Depois de criar a conexão, ela fica disponível na integração da Apigee e Application Integration. É possível usar a conexão em uma integração pela tarefa de conectores.
- Para entender como criar e usar a tarefa "Conectores" na integração da Apigee, consulte Tarefa "Conectores".
- Para entender como criar e usar a tarefa "Conectores" na Application Integration, consulte Tarefa "Conectores".
Receber ajuda da comunidade do Google Cloud
Poste suas dúvidas e converse sobre esse conector na comunidade do Google Cloud em Fóruns do Cloud.A seguir
- Entenda como suspender e retomar uma conexão.
- Entenda como monitorar o uso do conector.
- Saiba como ver os registros do conector.