Cloud Storage

O conetor do Google Cloud Storage permite-lhe estabelecer ligação a um Google Cloud Storage e realizar operações de transferência de ficheiros.

Antes de começar

Antes de usar o conetor do Cloud Storage, faça as seguintes tarefas:

  • No seu projeto do Google Cloud:
    • Certifique-se de que a conetividade de rede está configurada. Para obter informações sobre padrões de rede, consulte o artigo Conetividade de rede.
    • Conceda a função IAM roles/connectors.admin ao utilizador que está a configurar o conetor.
    • Conceda as seguintes funções de IAM à conta de serviço que quer usar para o conector:
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor
      • roles/storage.admin

      Uma conta de serviço é um tipo especial de Conta Google destinada a representar um utilizador não humano que precisa de autenticação e autorização para aceder a dados nas APIs Google. Se não tiver uma conta de serviço, tem de criar uma. O conector e a conta de serviço têm de pertencer ao mesmo projeto. Para mais informações, consulte Criar uma conta de serviço.

    • Ative os seguintes serviços:
      • secretmanager.googleapis.com (Secret Manager API)
      • connectors.googleapis.com (API Connectors)

      Para saber como ativar serviços, consulte o artigo Ativar serviços.

    Se estes serviços ou autorizações não tiverem sido ativados anteriormente para o seu projeto, é-lhe pedido que os ative quando configurar o conector.

Configure o conetor

Uma associação é específica de uma origem de dados. Isto significa que, se tiver muitas origens de dados, tem de criar uma associação separada para cada origem de dados. Para criar uma associação, faça o seguinte:

  1. Na Cloud Console, aceda à página Integration Connectors > Ligações e, de seguida, selecione ou crie um projeto do Google Cloud.

    Aceda à página Ligações

  2. Clique em + CRIAR NOVO para abrir a página Criar associação.
  3. Na secção Localização, escolha a localização para a ligação.
    1. Região: selecione uma localização na lista pendente.

      Para ver a lista de todas as regiões suportadas, consulte o artigo Localizações.

    2. Clique em SEGUINTE.
  4. Na secção Detalhes da associação, conclua o seguinte:
    1. Conetor: selecione Cloud Storage na lista pendente de conetores disponíveis.
    2. Versão do conetor: selecione a versão do conetor na lista pendente de versões disponíveis.
    3. No campo Nome da ligação, introduza um nome para a instância de ligação.

      Os nomes das associações têm de cumprir os seguintes critérios:

      • Os nomes das associações podem usar letras, números ou hífenes.
      • As letras têm de ser minúsculas.
      • Os nomes das associações têm de começar com uma letra e terminar com uma letra ou um número.
      • Os nomes das associações não podem exceder 49 carateres.
    4. Opcionalmente, introduza uma Descrição para a instância de associação.
    5. Opcionalmente, ative o Registo na nuvem e, em seguida, selecione um nível de registo. Por predefinição, o nível do registo está definido como Error.
    6. Conta de serviço: selecione uma conta de serviço que tenha as funções necessárias.
    7. Opcionalmente, configure as definições do nó de associação:

      • Número mínimo de nós: introduza o número mínimo de nós de ligação.
      • Número máximo de nós: introduza o número máximo de nós de ligação.

      Um nó é uma unidade (ou uma réplica) de uma ligação que processa transações. São necessários mais nós para processar mais transações para uma ligação e, inversamente, são necessários menos nós para processar menos transações. Para compreender como os nós afetam os preços dos conectores, consulte o artigo Preços dos nós de ligação. Se não introduzir valores, por predefinição, os nós mínimos são definidos como 2 (para uma melhor disponibilidade) e os nós máximos são definidos como 50.

    8. ID do projeto: o ID do projeto do Google Cloud onde os dados residem.
    9. Opcionalmente, clique em + ADICIONAR ETIQUETA para adicionar uma etiqueta à associação sob a forma de um par chave/valor.
    10. Clique em SEGUINTE.
  5. Rever: reveja a sua associação.
  6. Clique em Criar.

Entidades, operações e ações

Todos os conetores de integração oferecem uma camada de abstração para os objetos da aplicação ligada. Só pode aceder aos objetos de uma aplicação através desta abstração. A abstração é exposta como entidades, operações e ações.

  • Entidade: pode considerar uma entidade como um objeto ou uma coleção de propriedades na aplicação ou no serviço associado. A definição de uma entidade difere de um conetor para um conetor. Por exemplo, num conetor de base de dados, as tabelas são as entidades. Num conetor de servidor de ficheiros, as pastas são as entidades. Num conetor de sistema de mensagens, as filas são as entidades.

    No entanto, é possível que um conector não suporte ou não tenha entidades, caso em que a lista Entities estará vazia.

  • Operação: uma operação é a atividade que pode realizar numa entidade. Pode realizar qualquer uma das seguintes operações numa entidade:

    Selecionar uma entidade na lista disponível gera uma lista de operações disponíveis para a entidade. Para uma descrição detalhada das operações, consulte as operações de entidades da tarefa de conectores. No entanto, se um conector não suportar nenhuma das operações de entidades, essas operações não suportadas não são apresentadas na lista Operations.

  • Ação: uma ação é uma função de primeira classe que é disponibilizada à integração através da interface do conetor. Uma ação permite-lhe fazer alterações a uma ou mais entidades e varia de conetor para conetor. Normalmente, uma ação tem alguns parâmetros de entrada e um parâmetro de saída. No entanto, é possível que um conector não suporte nenhuma ação, caso em que a lista Actions está vazia.

Limitações do sistema

O conetor do Google Cloud Storage pode processar um máximo de 10 transações por segundo, por nó e limita todas as transações que excedam este limite. Por predefinição, os Integration Connectors atribuem 2 nós (para uma melhor disponibilidade) a uma ligação.

Para informações sobre os limites aplicáveis aos Integration Connectors, consulte Limites.

Ações

A ligação ao Google Cloud Storage suporta as seguintes ações:

Ação DownloadObject

A tabela seguinte descreve os parâmetros de entrada da ação DownloadObject.

Nome do parâmetro Obrigatória Tipo de dados Descrição
Grupo Sim String Nome do contentor onde o objeto a transferir está presente.
ObjectFilePath Não String Nome do objeto que deve ser transferido. Se não for especificado, todos os objetos do contentor especificado são transferidos.

Se o objeto a transferir estiver presente numa pasta secundária de um contentor, tem de indicar o caminho completo desse objeto. Por exemplo, para transferir logfile.txt que está presente no folderA de bucket_01, o caminho do objeto deve ser folderA/logfile.txt.

HasBytes Não Booleano Se deve transferir o conteúdo como bytes. Os valores válidos são true ou false. Se estiver definido como true, o conteúdo é transferido como uma string codificada em Base64.

Por predefinição, o campo HasBytes está definido como false.
UpdatedEndDate Não Data O intervalo de datas de fim para transferir objetos. Se não for especificado, os objetos são transferidos do UpdatedStartDate especificado até ao dia atual.
UpdatedStartDate Não Data O início do intervalo de datas para transferir objetos. Se não for especificado, os objetos são transferidos desde o início do período até à UpdatedEndDate.

Para ver exemplos de como configurar a ação DownloadObject, consulte a secção Exemplos.

Ação UploadObject

A tabela seguinte descreve os parâmetros de entrada da ação UploadObject.

Nome do parâmetro Obrigatória Tipo de dados Descrição
Grupo Sim String Nome do contentor onde o objeto vai ser carregado.
FolderPath Não String O caminho para a pasta onde o objeto deve ser carregado.
ContentBytes Não String Conteúdo a carregar sob a forma de bytes (string codificada em Base64).
HasBytes Não Booleano Se deve carregar conteúdo como bytes. Valores válidos: true ou false. Se estiver definido como true, o conteúdo que quer carregar deve ser uma string codificada em Base64.

Por predefinição, o campo HasBytes está definido como false.
Conteúdo Sim String O conteúdo a carregar.
ObjectName Não String Nome do objeto que vai ser carregado.

Para ver exemplos de como configurar a ação UploadObject, consulte a secção Exemplos.

Ação CopyObject

A tabela seguinte descreve os parâmetros de entrada da ação CopyObject.

Nome do parâmetro Obrigatória Tipo de dados Descrição
BucketSource Sim String Nome do contentor do qual quer copiar o objeto.
ObjectSource Sim String Caminho completo da pasta para onde quer copiar o objeto.
BucketDestination Sim String Nome do contentor para o qual quer copiar o objeto.
ObjectDestination Não String Caminho completo do destino, incluindo o nome do objeto. Se não especificar nenhum nome de objeto, o nome do objeto de origem é mantido.

Para ver exemplos de como configurar a ação CopyObject, consulte a secção Exemplos.

Ação MoveObject

A tabela seguinte descreve os parâmetros de entrada da ação MoveObject.

Nome do parâmetro Obrigatória Tipo de dados Descrição
BucketSource Sim String Nome do contentor a partir do qual quer mover o objeto.
ObjectSource Sim String Caminho completo da pasta para onde quer mover o objeto.
BucketDestination Sim String Nome do contentor para o qual quer mover o objeto.
ObjectDestination Não String Caminho completo do destino, incluindo o nome do objeto. Se não especificar nenhum nome de objeto, o nome do objeto de origem é mantido.

Ação DeleteObject

A tabela seguinte descreve os parâmetros de entrada da ação DeleteObject.

Nome do parâmetro Obrigatória Tipo de dados Descrição
BucketSource Sim String Nome do contentor onde o objeto a eliminar está presente.
ObjectSource Sim String Nome do objeto que quer eliminar.
Geração Não Duplo Versão do objeto a eliminar. Se estiver presente, elimina a revisão especificada do objeto em vez da versão mais recente, que é o comportamento predefinido.
IfGenerationMatch Não Duplo Torna a operação de eliminação condicional consoante a geração atual do objeto corresponder ao valor indicado. Se definir este valor como 0, a operação só é bem-sucedida se não existirem versões ativas do objeto.
IfGenerationNotMatch Não Duplo Torna a operação de eliminação condicional, dependendo se a geração atual do objeto corresponde ou não ao valor indicado. Se não existir nenhum objeto ativo, a pré-condição falha. Se definir este valor como 0, a operação só é bem-sucedida se existir uma versão em direto do objeto.
IfMetagenerationMatch Não Duplo Torna a operação de eliminação condicional consoante a metageração atual do objeto corresponder ou não ao valor especificado.
IfMetagenerationNotMatch Não Duplo Torna a operação de eliminação condicional, consoante a metageração atual do objeto não corresponder ao valor especificado.

Ação SignURL

A tabela seguinte descreve os parâmetros de entrada da ação SignURL que cria um URL assinado para o objeto especificado.

Nome do parâmetro Obrigatória Tipo de dados Descrição
Grupo Sim String O nome do contentor onde o objeto reside.
Objeto Sim String O nome do objeto para o qual gerar o URL assinado.
RequestMethod Não String O método que o pedido assinado vai usar. O valor predefinido é GET.
Localização Não String Localização do depósito especificado. O valor predefinido é auto.
ActiveDateTime Não String A data/hora em que o URL assinado fica ativo. Se não for especificado, é usada a data/hora atual.
Consulta Não String A string de consulta que tem de ser incluída quando usar o SignedURL. Se não for especificada, não é usada nenhuma string de consulta.
CustomHeaders Não String Uma lista separada por vírgulas de name=value dos cabeçalhos a usar com o SignedURL. Se não for especificado, não são usados cabeçalhos personalizados.
ExpiresIn Sim String A hora de validade do URL assinado deve estar no formato: 1d2h3m4s. O valor máximo é 7d0h0m0s.
ID de acesso HMAC Sim String O ID de acesso HMAC. Para obter informações, consulte o artigo Chaves de HMAC.
Segredo HMAC Sim String O segredo HMAC.

Exemplos

Os exemplos nesta secção descrevem as seguintes operações:

  • Apresentar todos os objetos
  • Apresenta todos os objetos num contentor
  • Liste objetos usando o filtro LIKE para o nome
  • Apresente todos os contentores
  • Transfira um objeto
  • Transfira um objeto binário
  • Carregue um objeto binário para um contentor
  • Carregue um objeto para um contentor
  • Carregue um objeto para uma pasta
  • Copie um objeto
  • Mova um objeto
  • Elimine um objeto
  • Crie um URL assinado para um objeto

A tabela seguinte lista os cenários de exemplo e a configuração correspondente na tarefa Conectores:

Tarefa Configuração
Apresentar todos os objetos
  1. Na caixa de diálogo Configure connector task, clique em Entities.
  2. Selecione a entidade Objects e, em seguida, a operação List.
  3. Clique em Concluído.

Esta opção apresenta todos os objetos em todos os contentores. Os objetos estão listados no parâmetro de resposta ConnectorsconnectorOutputPayload da tarefa.
Apresenta todos os objetos num contentor
  1. Na caixa de diálogo Configure connector task, clique em Entities.
  2. Selecione a entidade Objects e, em seguida, a operação List.
  3. Clique em Concluído.
  4. Defina o filterClause para o nome do contentor a partir do qual quer listar os objetos. Para definir a cláusula, na secção Task Input da tarefa Connectors, clique em filterClause e, de seguida, introduza Bucket = 'BUCKET_NAME' no campo Valor predefinido. Por exemplo, Bucket = 'bucket_01'.
Liste objetos usando o filtro LIKE para o nome
  1. Na caixa de diálogo Configure connector task, clique em Entities.
  2. Selecione a entidade Objects e, em seguida, a operação List.
  3. Clique em Concluído.
  4. Defina o filterClause para o nome do contentor do qual quer listar os objetos. Para definir a cláusula, na secção Task Input da tarefa Connectors, clique em filterClause e, de seguida, introduza Name LIKE 'NAME%' AND Bucket = 'BUCKET_NAME' no campo Valor predefinido.

    Por exemplo, Name LIKE 'Operations%' AND Bucket = 'OperationsBucket'.
Apresente todos os contentores
  1. Na caixa de diálogo Configure connector task, clique em Entities.
  2. Selecione a entidade Buckets e, em seguida, a operação List.
  3. Clique em Concluído.
Transfira um objeto
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação DownloadObject e, de seguida, clique em Concluído.
  3. Na secção Entrada da tarefa da tarefa Conectores, clique em connectorInputPayload e, de seguida, introduza um valor semelhante ao seguinte no campo Default Value: 
    {
  "Bucket": "bucket-test-01",
  "ObjectFilePath": "logfile.txt"
}

    4. Este exemplo transfere o ficheiro logfile.txt. O conteúdo do ficheiro transferido está disponível no formato JSON no parâmetro de resposta da Connectors tarefaconnectorOutputPayload.
Transfira um objeto binário

Os passos para transferir um objeto binário são os mesmos que para transferir um objeto normal, conforme descrito anteriormente. Além disso, tem de especificar HasBytes como true no campo connectorInputPayload. Esta ação transfere o objeto como uma string codificada em Base64. Valor de exemplo para o campo connectorInputPayload:

{
"Bucket": "bucket-test-01",
"ObjectFilePath": "image01.png",
"HasBytes" : true
}

Se a transferência for bem-sucedida, o resultado no campo connectorOutputPayload será semelhante ao seguinte:

{
"Success": "true",
"ContentBytes": "SGVsbG8gdGVzdCE\u003d"
}

Por predefinição, o campo HasBytes está definido como false.

Se o ficheiro contiver carateres especiais, como ä, Ø ou Thành, faça o seguinte:

  1. Codifique em UTF-8: codifique o ficheiro em UTF-8 para processar os carateres especiais.
  2. Converter para Base64: converta o ficheiro para Base64 para garantir que o texto original permanece intacto.
  3. Descodifique a string Base64: descodifique o ficheiro para a string Base64 para obter o valor original com os carateres especiais.
Carregue um objeto binário para um contentor
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação UploadObject e, de seguida, clique em Concluído.
  3. Na secção Entrada de tarefas da tarefa Conetores, clique em connectorInputPayload e, de seguida, introduza o seguinte no campo Default Value: 
    {
"ContentBytes": "SGVsbG8gVGVzdCE=",
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01",
"HasBytes": true
}

    4. Este exemplo cria o ficheiro test-file-01 no contentor bucket-test-01. Se existir um ficheiro com o nome test-file-01, este é substituído.
Carregue um objeto para um contentor
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação UploadObject e, de seguida, clique em Concluído.
  3. Na secção Entrada de tarefas da tarefa Conetores, clique em connectorInputPayload e, de seguida, introduza o seguinte no campo Default Value: 
    {
"Content": "Hello test!",
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01.txt"
}

    4. Este exemplo cria o ficheiro test-file-01.txt com o conteúdo Hello test! no contentor bucket-test-01. Se existir um ficheiro com o nome test-file-01.txt, este é substituído.
Carregue um objeto para uma pasta
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação UploadObject e, de seguida, clique em Concluído.
  3. Na secção Entrada de tarefas da tarefa Conetores, clique em connectorInputPayload e, de seguida, introduza o seguinte no campo Default Value: 
    {
"Content": "Hello test!",
"Bucket": "bucket-test-01",
"FolderPath": "folderA",
"ObjectName": "test-file-01.txt"
}

    4. Este exemplo cria o ficheiro test-file-01.txt com o conteúdo Hello test! na pasta bucket-test-01 de folderA. Se a pasta tiver um ficheiro existente com o nome test-file-01.txt, este é substituído.
Copie um objeto
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação CopyObject e, de seguida, clique em Concluído.
  3. Na secção Entrada de tarefas da tarefa Conetores, clique em connectorInputPayload e, de seguida, introduza o seguinte no campo Default Value: 
    {
"BucketSource": "bucket_01",
"ObjectSource": "folderA/logfile.txt",
"BucketDestination": "bucket_02",
"ObjectDestination": "folderB/logfile.txt"
}

    4. Este exemplo copia o ficheiro folderA/logfile.txt de bucket_01 para folderB/logfile.txt em bucket_02.

Se a cópia for bem-sucedida, a saída no campo connectorOutputPayload é semelhante à seguinte:

{
"Success": "true"
}
Mova um objeto
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação MoveObject e, de seguida, clique em Concluído.
  3. Na secção Entrada de tarefas da tarefa Conetores, clique em connectorInputPayload e, de seguida, introduza o seguinte no campo Default Value: 
    {
"BucketSource": "bucket_01",
"ObjectSource": "folderA/logfile.txt",
"BucketDestination": "bucket_02",
"ObjectDestination": "folderB/logfile.txt"
}

    4. Este exemplo move o ficheiro folderA/logfile.txt de bucket_01 para folderB/logfile.txt em bucket_02.

Se a cópia for bem-sucedida, a saída no campo connectorOutputPayload é semelhante à seguinte:

{
"Success": "true"
}
Elimine um objeto
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação DeleteObject e, de seguida, clique em Concluído.
  3. Na secção Entrada de tarefas da tarefa Conetores, clique em connectorInputPayload e, de seguida, introduza o seguinte no campo Default Value: 
    {
"BucketSource": "bucket_01",
"ObjectSource": "logfile.txt"
}

    4. Este exemplo elimina o ficheiro logfile.txt de bucket_01.

Se a cópia for bem-sucedida, a saída no campo connectorOutputPayload é semelhante à seguinte:

{
"Success": "true"
}
Crie um URL assinado para um objeto
  1. Na caixa de diálogo Configure connector task, clique em Actions.
  2. Selecione a ação SignURL e, de seguida, clique em Concluído.
  3. Na secção Entrada de tarefas da tarefa Conetores, clique em connectorInputPayload e, de seguida, introduza o seguinte no campo Default Value: 
    {
"Bucket": "bucket-test-01",
"ObjectName" : "test-file-01.txt"
}

    4. Este exemplo cria um URL assinado para o ficheiro test-file-01.txt que se encontra no contentor bucket-test-01. Se a ação for bem-sucedida, recebe o URL assinado na resposta de forma semelhante ao seguinte:

    {
"Success": "true",
"SignURL": "https://storage.googleapis.com/example-bucket/cat.jpeg?X-Goog-Algorithm=
GOOG4-RSA-SHA256&X-Goog-Credential=example%40example-project.iam.gserviceaccount.com
%2F20181026%2Fus-central1%2Fstorage%2Fgoog4_request&X-Goog-Date=20181026T18
1309Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&X-Goog-Signature=247a2aa45f16
9edf4d187d54e7cc46e4731b1e6273242c4f4c39a1d2507a0e58706e25e3a85a7dbb891d62afa849
6def8e260c1db863d9ace85ff0a184b894b117fe46d1225c82f2aa19efd52cf21d3e2022b3b868dc
c1aca2741951ed5bf3bb25a34f5e9316a2841e8ff4c530b22ceaa1c5ce09c7cbb5732631510c2058
0e61723f5594de3aea497f195456a2ff2bdd0d13bad47289d8611b6f9cfeef0c46c91a455b94e90a
66924f722292d21e24d31dcfb38ce0c0f353ffa5a9756fc2a9f2b40bc2113206a81e324fc4fd6823
a29163fa845c8ae7eca1fcf6e5bb48b3200983c56c5ca81fffb151cca7402beddfc4a76b13344703
2ea7abedc098d2eb14a7"
}

Considerações

  • Um objeto transferível pode ter um tamanho máximo de 10 MB.
  • Não pode carregar vários ficheiros através da ação UploadObject. Só pode carregar um único ficheiro.

Crie ligações com o Terraform

Pode usar o recurso do Terraform para criar uma nova associação.

Para saber como aplicar ou remover uma configuração do Terraform, consulte os comandos básicos do Terraform.

Para ver um modelo do Terraform de exemplo para a criação de ligações, consulte o modelo de exemplo.

Quando criar esta associação através do Terraform, tem de definir as seguintes variáveis no ficheiro de configuração do Terraform:

Nome do parâmetro Tipo de dados Obrigatória Descrição
project_id STRING True O ID do projeto do Google Cloud onde os dados residem.

Use a ligação do Cloud Storage numa integração

Depois de criar a ligação, esta fica disponível no Apigee Integration e no Application Integration. Pode usar a ligação numa integração através da tarefa Conectores.

  • Para compreender como criar e usar a tarefa Connectors no Apigee Integration, consulte o artigo Tarefa Connectors.
  • Para compreender como criar e usar a tarefa Connectors na integração de aplicações, consulte o artigo Tarefa Connectors.

Obtenha ajuda da comunidade do Google Cloud

Pode publicar as suas perguntas e discutir este conector na comunidade do Google Cloud nos Fóruns do Cloud.

O que se segue?