Transferir de URLs públicos para o Cloud Storage

O Serviço de transferência do Cloud Storage pode copiar arquivos de uma lista de URLs públicos para o bucket do Cloud Storage.

Ao criar uma transferência, você fornece um link para um arquivo de valores separados por tabulação (TSV) que contém os URLs e detalhes dos objetos a serem transferidos. O arquivo TSV pode ser hospedado em qualquer local HTTP ou HTTPS de acesso público ou armazenado em um bucket do Cloud Storage.

Esta página explica como criar uma lista de URLs e transmiti-la ao comando de criação de jobs.

Requisitos do arquivo de origem

  • Os URLs precisam ser de acesso público e usar protocolos HTTP ou HTTPS.
  • O servidor que hospeda cada objeto:
    • Não pode negar o acesso ao objeto com um robots.txt.
    • Aceita solicitações Range.
    • Retorna um cabeçalho Content-Length em cada resposta.

Formato da lista de URL

Uma lista de URLs precisa obedecer aos seguintes requisitos:

  • O arquivo precisa ser formatado como valores separados por tabulação.
  • Os URLs precisam estar em ordem lexicográfica UTF-8.
  • A primeira linha precisa especificar TsvHttpData-1.0.
  • Após a primeira linha, especifique um objeto por linha.
  • Cada linha precisa conter o URL e também pode conter o tamanho do arquivo e a soma de verificação MD5 codificada em base64 do objeto.

Veja a seguir um arquivo TSV de amostra que especifica dois objetos a serem transferidos. Nesta página, as guias são renderizadas como espaços. No seu arquivo, use guias entre os campos.

TsvHttpData-1.0
https://example.com/myfile.pdf    1357    wHENa08V36iPYAsOa2JAdw==
https://example2.com/images/dataset1/flower.png    2468    R9acAaveoPd2y8nniLUYbw==

Cada linha contém:

  • O URL HTTP ou HTTPS de um objeto de origem.

  • (Opcional) O tamanho do objeto em bytes.

    Certifique-se de que o tamanho especificado corresponda ao tamanho real do objeto quando ele for buscado. Se o tamanho do objeto recebido pelo Cloud Storage não corresponder ao tamanho especificado, a transferência do objeto falhará.

  • (Opcional) A soma de verificação MD5 codificada em base64 do objeto.

    Verifique se a soma de verificação MD5 especificada corresponde à soma de verificação MD5 calculada a partir dos bytes transferidos. Se a soma de verificação MD5 do objeto recebido pelo Cloud Storage não corresponder à soma de verificação MD5 especificada, a transferência do objeto falhará.

Embora o tamanho do objeto e os valores de soma de verificação MD5 sejam opcionais, recomendamos incluí-los para garantir a integridade dos dados.

Como hospedar a lista de URLs

A lista de URLs pode ser hospedada em um destes dois locais:

  • Um URL de acesso público.

  • Um bucket do Cloud Storage, ao qual o agente de serviço do Serviço de transferência do Cloud Storage recebeu acesso.

URLs de acesso público

Ao armazenar a lista de URLs em um URL de acesso público, os seguintes requisitos se aplicam:

  • O URL precisa começar com http:// ou https://.
  • O servidor precisa definir um cabeçalho Etag forte na resposta HTTP quando retornar a lista de URLs.

Por exemplo, você pode armazenar a lista em um bucket do Cloud Storage e compartilhar o objeto publicamente para gerar um link para ele.

Buckets do Cloud Storage

Para evitar armazenar sua lista em um local público, você pode armazená-la em um bucket do Cloud Storage e conceder acesso ao agente de serviço do Serviço de transferência do Cloud Storage.

O agente de serviço precisa receber as seguintes permissões:

  • A permissão storage.object.get no objeto. Isso pode ser concedido ao atribuir a função roles/storage.legacyObjectReader ao bucket ou com uma função personalizada.
  • A permissão storage.buckets.get no bucket. Isso pode ser concedido ao atribuir o papel roles/storage.legacyBucketReader ou com uma função personalizada.

Para conceder permissões ao agente de serviço:

Encontre o e-mail do agente de serviço

  1. Acesse a googleServiceAccounts.get página de referência.

    Você verá um painel interativo com o título Testar este método.

  2. No painel, em Parâmetros de solicitação, insira o ID do projeto. O projeto especificado aqui precisa ser o projeto que você está usando para gerenciar o Serviço de transferência do Cloud Storage, que pode ser diferente do projeto do bucket da lista de URLs.

  3. Clique em Executar.

O e-mail do agente de serviço é retornado como o valor de accountEmail e usa o formato project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.

Copie esse valor.

Conceder os papéis necessários

Para conceder o papel roles/storage.objectViewer e o roles/storage.bucketViewer papel ao agente de serviço no bucket que contém a lista de URLs, siga as instruções em Definir e gerenciar políticas do IAM em buckets.

O principal que você está adicionando é o endereço de e-mail do agente de serviço. Se necessário, o identificador principal é serviceAccount. Por exemplo, serviceAccount:project-PROJECT_NUMBER@storage-transfer-service.iam.gserviceaccount.com.

Criar um job de transferência de lista de URLs

Para especificar uma lista de URLs ao criar um job de transferência, siga estas instruções:

Google Cloud Console do

Siga as instruções em Criar um job de transferência.

Ao escolher uma origem:

  1. Em Tipo de origem, selecione Lista de URLs e clique em Próxima etapa.

  2. Em URL do arquivo TSV, insira o URL do arquivo de valores separados por tabulação (TSV). O URL é um endereço HTTP/HTTPS (por exemplo, https://example.com/urllist.tsv) ou um caminho do Cloud Storage (por exemplo, gs://my-bucket/urllist.tsv).

CLI gcloud

Para criar um novo job de transferência, use o comando gcloud transfer jobs create.

gcloud transfer jobs create \
  SOURCE DESTINATION

Para transferências de lista de URLs, o valor de SOURCE é o URL do arquivo TSV. O URL é um endereço HTTP/HTTPS (por exemplo, https://example.com/urllist.tsv) ou um caminho do Cloud Storage (por exemplo, gs://my-bucket/urllist.tsv).

Para mais informações sobre como criar transferências usando a CLI gcloud, consulte Criar jobs de transferência.

REST

Para criar um job de transferência de lista de URLs usando a API REST, especifique o URL do arquivo TSV no campo listUrl:

{
  "projectId": "PROJECT_ID",
  "transferSpec": {
    "httpDataSource": {
      "listUrl": "URL"
    },
    "gcsDataSink": {
      "bucketName": "DESTINATION_BUCKET"
    }
  },
  "status": "ENABLED"
}

O valor de URL é um endereço HTTP/HTTPS (por exemplo, https://example.com/urllist.tsv) ou um caminho do Cloud Storage (por exemplo, gs://my-bucket/urllist.tsv).

Para mais detalhes sobre como criar transferências usando a API REST, consulte a referência da API REST.