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 detalhes dos objetos a serem transferidos. O arquivo TSV pode ser hospedado em qualquer local HTTP ou HTTPS acessível publicamente 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 acessíveis publicamente 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 pode conter o tamanho do arquivo e a soma de verificação MD5 codificada em base64 do objeto.

Confira a seguir um arquivo TSV de amostra que especifica dois objetos a serem transferidos. Observe que, nesta página, as guias são renderizadas como espaços. Para seu próprio 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 checksum MD5 sejam opcionais, recomendamos que você os inclua para garantir a integridade dos dados.

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 foi concedido acesso.

URLs acessíveis publicamente

Ao armazenar a lista de URLs em um URL acessível ao 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, é 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, armazene-a em um bucket do Cloud Storage e conceda acesso ao agente de serviço para o Serviço de transferência do Cloud Storage.

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

  • A permissão storage.object.get no objeto. Isso pode ser concedido concedendo o papel roles/storage.legacyObjectReader no bucket ou com um papel personalizado.
  • A permissão storage.buckets.get no bucket. Isso pode ser concedido 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 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 os papéis roles/storage.objectViewer e roles/storage.bucketViewer 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

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

Ao escolher uma fonte:

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