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 seu 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 os detalhes dos objetos a serem transferidos. O arquivo TSV pode ser hospedado em qualquer local HTTP ou HTTPS acessível publicamente ou pode ser armazenado em um bucket do Cloud Storage.

Nesta página, explicamos 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 acessíveis publicamente e usar os 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 atender 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.
  • Depois da 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 exemplo de arquivo TSV que especifica dois objetos para transferência. Nesta página, as tabulações são renderizadas como espaços. No seu arquivo, use tabulações 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 os valores de tamanho do objeto e checksum MD5 sejam opcionais, recomendamos incluí-los para garantir a integridade de dados.

Hospedar a lista de URLs

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

  • Um URL acessível ao 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 acessíveis ao público

Ao armazenar a lista de URLs em um URL acessível publicamente, 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 retorna a lista de URLs.

Por exemplo, é possível 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 o armazenamento da lista em um local público, é possível 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.objects.get no objeto. Isso pode ser feito concedendo o papel roles/storage.objectViewer no bucket ou com um papel personalizado.
  • A permissão storage.buckets.get no bucket. Isso pode ser feito concedendo o papel roles/storage.legacyBucketReader ou com um papel personalizado.

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

Encontre o e-mail do agente de serviço

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

    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..

Copie esse valor.

Conceder os papéis necessários

Para conceder os papéis roles/storage.objectViewer e roles/storage.legacyBucketReader 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..

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:

Console do Google Cloud

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 em um 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 da 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 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.