Como exportar e importar entidades

Veja nesta página como exportar e importar entidades do Firestore no modo Datastore usando o serviço gerenciado de exportação e importação. O serviço de exportação e importação gerenciado está disponível por meio do Console do Cloud, da CLI do Google Cloud e da API Admin do Datastore (REST, RPC).

Com o serviço gerenciado de exportação e importação, é possível se recuperar de exclusão acidental de dados e exportá-los para processamento off-line. É possível exportar todas as entidades ou apenas tipos específicos de entidades. Da mesma forma, é possível importar todos os dados de uma exportação ou apenas tipos específicos. Ao usar o serviço gerenciado de exportação e importação, considere o seguinte:

  • O serviço de exportação usa leituras com consistência posterior. Não é possível presumir que uma exportação aconteça em um único momento. A exportação pode incluir entidades gravadas após o início da exportação e excluir entidades gravadas antes do início da exportação.

  • Uma exportação não contém índices. Quando você importa dados, os índices necessários são recriados automaticamente usando as definições de índice atuais do seu banco de dados. As configurações de índice com valor da propriedade por entidade são exportadas e respeitadas durante a importação.

  • As importações não atribuem novos IDs às entidades. Elas usam os códigos que existiam no momento da exportação e substituem qualquer entidade atual com o mesmo código. Durante uma importação, os IDs são reservados durante o tempo que as entidades estão sendo importadas. Esse recurso evita conflitos de ID com novas entidades se as gravações estiverem ativadas enquanto uma importação está em execução.

  • Se uma entidade em seu banco de dados não for afetada por uma importação, ela permanecerá no banco de dados após esse processo.

  • Os dados exportados de um banco de dados do modo Datastore podem ser importados para outro banco de dados do modo Datastore, mesmo um banco de dados em outro projeto.

  • O serviço de exportação e importação gerenciado limita o número de exportações e importações simultâneas a 50 e permite no máximo 20 solicitações de exportação e importação por minuto para um projeto. Para cada solicitação, o serviço limita o número de combinações de filtro de entidades a 100.

  • A saída de uma exportação gerenciada usa o formato de registro LevelDB.

  • Para importar apenas um subconjunto de entidades ou importar dados para o BigQuery, especifique um filtro de entidade na exportação.

Antes de começar

Antes de usar o serviço gerenciado de exportação e importação, é necessário concluir as tarefas a seguir.

  1. Ative o faturamento do projeto do Google Cloud. Somente projetos do Google Cloud com faturamento ativado podem usar a funcionalidade de exportação e importação.

  2. Crie um bucket do Cloud Storage no mesmo local do banco de dados do Firestore no modo Datastore. Não é possível usar um intervalo de pagamentos do solicitante para operações de exportação e importação.

  3. Atribua um papel do IAM à sua conta de usuário que conceda a permissão datastore.databases.export, se você estiver exportando dados, ou a permissão datastore.databases.import, se estiver importando dados. O papel Datastore Import Export Admin, por exemplo, concede as duas permissões.

  4. Se o bucket do Cloud Storage estiver em outro projeto, permita que a conta de serviços padrão do projeto acesse o bucket.

Configurar gcloud para seu projeto

Se você planeja usar gcloud para iniciar as operações de importação e exportação, configure gcloud e conecte-se ao seu projeto de uma das seguintes maneiras:

Como iniciar operações de exportação e importação gerenciadas

Esta seção descreve como iniciar uma operação de exportação ou importação gerenciada.

Exportando todas as entidades

Console

  1. Acesse a página Importar/Exportar do Datastore no Console do Google Cloud.

    Acessar a página "Importar/Exportar"

  2. Clique em Exportar.

  3. Configure o campo Namespace como All Namespaces e o campo Tipo como All Kinds.

  4. Abaixo de Destino, insira o nome do bucket do Cloud Storage.

  5. Clique em Exportar.

O console retorna à página Importar/Exportar. Um alerta informa o sucesso ou a falha da sua solicitação de exportação gerenciada.

gcloud

Use o comando gcloud datastore export para exportar todas as entidades do seu banco de dados. 

 gcloud datastore export gs://bucket-name --async

em que bucket-name é o nome do bucket do Cloud Storage e um prefixo opcional, por exemplo, bucket-name/datastore-exports/export-name. Não é possível reutilizar o mesmo prefixo para outra operação de exportação. Se você não fornecer um prefixo de arquivo, o serviço de exportação gerenciado criará um com base no horário atual.

Use a sinalização --async para evitar que gcloud espere a operação ser concluída. Se você omitir a sinalização --async, poderá digitar Ctrl+c para parar de esperar uma operação. Essa ação não cancelará a operação.

descanso

Antes de usar qualquer um dos dados da solicitação, faça as substituições a seguir:

  • project-id: o ID do projeto;
  • bucket-name: o nome do bucket do Cloud Storage

Método HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:export

Corpo JSON da solicitação: 

{
  "outputUrlPrefix": "gs://bucket-name",
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante à seguinte:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T18:42:26.591949Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T18:42:26_85726"
  }
}
A resposta é uma operação de longa duração, que pode ser verificada para ver se foi concluída.

Exportar tipos ou namespaces específicos

Para exportar um subconjunto específico de tipos e/ou namespaces, forneça um filtro de entidade com valores para tipos e IDs de namespace. Cada solicitação é limitada a 100 combinações de filtros de entidade, em que cada combinação de tipo filtrado e namespace conta como um filtro separado para esse limite.

Console

No console, é possível selecionar todos os tipos ou um tipo específico. Da mesma forma, é possível selecionar todos os namespaces ou um namespace específico.

Para especificar uma lista de namespaces e tipos a serem exportados, use gcloud.

  1. Acesse a página Exportação do Datastore no Console do Google Cloud.

    Acessar a página "Exportação do Datastore"

  2. Clique em Exportar.

  3. Defina o campo Namespace como All Namespaces ou o nome de um dos seus namespaces.

  4. Defina o campo Tipo como All Kinds ou o nome de um tipo.

  5. Em Destino, insira o nome do bucket do Cloud Storage.

  6. Clique em Exportar.

O console retorna à página Importar/Exportar. Um alerta informa o sucesso ou a falha da sua solicitação de exportação gerenciada.

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name --async

em que bucket-name é o nome do bucket do Cloud Storage e um prefixo opcional, por exemplo, bucket-name/datastore-exports/export-name. Não é possível reutilizar o mesmo prefixo para outra operação de exportação. Se você não fornecer um prefixo de arquivo, o serviço de exportação gerenciado criará um com base no horário atual.

Use a sinalização --async para evitar que gcloud espere a operação ser concluída. Se você omitir a sinalização --async, poderá digitar Ctrl+c para parar de esperar uma operação. Essa ação não cancelará a operação.

descanso

Antes de usar qualquer um dos dados da solicitação, faça as substituições a seguir:

  • project-id: o ID do projeto;
  • bucket-name: o nome do bucket do Cloud Storage
  • kind: o tipo de entidade
  • namespace: o ID do namespace (use "" para o ID de namespace padrão)

Método HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:export

Corpo JSON da solicitação: 

{
  "outputUrlPrefix": "gs://bucket-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante à seguinte:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:17:36.232704Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://bucket-name/2019-09-18T21:17:36_82974"
  }
}
A resposta é uma operação de longa duração, que pode ser verificada para ver se foi concluída.

Arquivos de metadados

Uma operação de exportação cria um arquivo de metadados para cada par de namespace/tipo especificado. Os arquivos de metadados geralmente são denominados NAMESPACE_NAME_KIND_NAME.export_metadata. No entanto, se um namespace ou tipo criar um nome de objeto do Cloud Storage inválido, o arquivo será chamado de export[NUM].export_metadata.

Os arquivos de metadados são buffers de protocolo e podem ser decodificados com o compilador de protocolo protoc. Por exemplo, é possível decodificar um arquivo de metadados para determinar o namespace e os tipos que os arquivos de exportação contêm:

protoc --decode_raw < export0.export_metadata

Como importar todas as entidades

Console

  1. Acesse a página Importação do Datastore no Console do Google Cloud.

    Acessar a página Importação do Datastore

  2. Clique em Import.

  3. No campo File, clique em Procurar e selecione um arquivo overall_export_metadata.

  4. Configure o campo Namespace como All Namespaces e o campo Tipo como All Kinds.

  5. Clique em Import.

O console retorna à página Importar/Exportar. Um alerta informa o sucesso ou a falha da sua solicitação de importação gerenciada.

gcloud

Use o comando gcloud datastore import para importar todas as entidades que foram exportadas anteriormente com o serviço de exportação gerenciado.

gcloud datastore import gs://bucket-name/file-path/file-name.overall_export_metadata --async

em que bucket-name/file-path/file-name é o caminho para o arquivo overall_export_metadata no bucket do Cloud Storage.

Use a sinalização --async para evitar que gcloud espere a operação ser concluída. Se você omitir a sinalização --async, poderá digitar Ctrl+c para parar de esperar uma operação. Essa ação não cancelará a operação.

descanso

Antes de usar qualquer um dos dados da solicitação, faça as substituições a seguir:

  • project-id: o ID do projeto;
  • bucket-name: o nome do bucket do Cloud Storage
  • object-name: o nome do objeto do Cloud Storage (exemplo: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata)

Método HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:import

Corpo JSON da solicitação: 

{
  "inputUrl": "gs://bucket-name/object-name",
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante à seguinte:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:25:02.863621Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {},
    "inputUrl": "gs://bucket-name/2019-09-18T18:42:26_85726/2019-09-18T18:42:26_85726.overall_export_metadata"
  }
}
A resposta é uma operação de longa duração, que pode ser verificada para ver se foi concluída.

Como localizar seu arquivo overall_export_metadata

É possível determinar o valor a ser usado para o local de importação usando o navegador do Cloud Storage no Console do Google Cloud:

Abra o navegador do Cloud Storage

Também é possível listar e descrever as operações concluídas. O campo outputURL mostra o nome do arquivo overall_export_metadata:

"outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Como importar tipos ou namespaces específicos

Para importar um subconjunto específico de tipos e/ou namespaces, forneça um filtro de entidade com valores para tipos e IDs de namespace.

Só será possível especificar tipos e namespaces se os arquivos de exportação tiverem sido criados com um filtro de entidade. Não é possível importar um subconjunto de tipos e namespaces de uma exportação de todas as entidades.

Console

No console, é possível selecionar todos os tipos ou um tipo específico. Da mesma forma, é possível selecionar todos os namespaces ou um namespace específico.

Para especificar uma lista de namespaces e tipos a serem importados, use gcloud.

  1. Acesse a página Importação do Datastore no Console do Google Cloud.

    Acessar a página Importação do Datastore

  2. Clique em Import.

  3. No campo File, clique em Procurar e selecione um arquivo overall_export_metadata.

  4. Defina o campo Namespace como All Namespaces ou como um namespace específico.

  5. Defina o campo Tipo como All Kinds ou um tipo específico.

  6. Clique em Import.

O console retorna à página Importar/Exportar. Um alerta informa o sucesso ou a falha da sua solicitação de importação gerenciada.

gcloud

gcloud datastore import --kinds="KIND1,KIND2" --namespaces="(default),NAMESPACE2" gs://bucket-name/file-path/file-name.overall_export_metadata --async

em que bucket-name/file-path/file-name é o caminho para o arquivo overall_export_metadata no bucket do Cloud Storage.

Use a sinalização --async para evitar que gcloud espere a operação ser concluída. Se você omitir a sinalização --async, poderá digitar Ctrl+c para parar de esperar uma operação. Essa ação não cancelará a operação.

descanso

Antes de usar qualquer um dos dados da solicitação, faça as substituições a seguir:

  • project-id: o ID do projeto;
  • bucket-name: o nome do bucket do Cloud Storage
  • object-name: o nome do objeto do Cloud Storage (exemplo: 2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata)
  • kind: o tipo de entidade
  • namespace: o ID do namespace (use "" para o ID de namespace padrão)

Método HTTP e URL: 

POST https://datastore.googleapis.com/v1/projects/project-id:import

Corpo JSON da solicitação: 

{
  "inputUrl": "gs://bucket-name/object-name",
  "entityFilter": {
    "kinds": ["kind"],
    "namespaceIds": ["namespace"],
  },
}

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante à seguinte:

{
  "name": "projects/project-id/operations/operation-id",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ImportEntitiesMetadata",
    "common": {
      "startTime": "2019-09-18T21:51:02.830608Z",
      "operationType": "IMPORT_ENTITIES",
      "state": "PROCESSING"
    },
    "entityFilter": {
      "kinds": [
        "Task"
      ],
      "namespaceIds": [
        ""
      ]
    },
    "inputUrl": "gs://bucket-name/2019-09-18T21:49:25_96833/2019-09-18T21:49:25_96833.overall_export_metadata"
  }
}
A resposta é uma operação de longa duração, que pode ser verificada para ver se foi concluída.

Transformações de importação

Ao importar entidades de outro projeto, lembre-se de que as chaves de entidade incluem o ID do projeto. Uma operação de importação atualiza chaves de entidade e propriedades de referência de chave nos dados de importação com o ID do projeto de destino. Se a atualização aumentar seus tamanhos de entidade, ela poderá causar erros de entradas ""entity"muito grande ou ""index".

Para evitar erros, importe para um projeto de destino com um código de projeto menor. Isso não afeta as operações de importação com dados do mesmo projeto.

Como gerenciar operações de longa duração

As operações de importação e exportação gerenciadas são de longa duração. Essas chamadas de método podem demorar um pouco para serem concluídas.

Depois de iniciar uma operação de exportação ou importação, o modo Datastore atribui um nome exclusivo a ela. Use esse nome para excluir, cancelar ou verificar a operação.

Os nomes das operações são prefixados com projects/[PROJECT_ID]/databases/(default)/operations/, por exemplo:

projects/project-id/databases/(default)/operations/ASA1MTAwNDQxNAgadGx1YWZlZAcSeWx0aGdpbi1zYm9qLW5pbWRhEgopEg

É possível omitir o prefixo ao especificar um nome de operação para comandos gcloud.

Como listar todas as operações de longa duração

Veja as operações contínuas e as concluídas recentemente das seguintes maneiras. As operações são listadas por alguns dias após a conclusão:

Console

É possível visualizar uma lista das operações de exportação e importação mais recentes na página Importar/Exportar do modo Datastore do Console do Google Cloud.

Acessar a página "Importar/Exportar"

gcloud

Para listar operações de longa duração, use o comando gcloud datastore operations list. 

gcloud datastore operations list

Por exemplo, uma operação de exportação concluída recentemente mostra as seguintes informações:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

descanso

Antes de usar qualquer um dos dados da solicitação, faça as substituições a seguir:

  • project-id: o ID do projeto;

Método HTTP e URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations

Para enviar a solicitação, expanda uma destas opções:

Veja as informações sobre a resposta abaixo.

Por exemplo, uma operação de exportação concluída recentemente mostra as seguintes informações:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        "common": {
          "startTime": "2017-12-05T23:01:39.583780Z",
          "endTime": "2017-12-05T23:54:58.474750Z",
          "operationType": "EXPORT_ENTITIES"
        },
        "progressEntities": {
          "workCompleted": "21933027",
          "workEstimated": "21898182"
        },
        "progressBytes": {
          "workCompleted": "12421451292",
          "workEstimated": "9759724245"
        },
        "entityFilter": {
          "namespaceIds": [
            ""
          ]
        },
        "outputUrlPrefix": "gs://bucket-name"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://bucket-name/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

Verificar o status da operação

Para visualizar o status de uma operação de longa duração:

Console

É possível visualizar uma lista das operações de exportação e importação mais recentes na página Importar/Exportar do modo Datastore do Console do Google Cloud.

Acessar a página "Importar/Exportar"

gcloud

Use o comando operations describe para mostrar o status de uma operação de longa duração.

gcloud datastore operations describe operation-name

descanso

Antes de usar qualquer um dos dados da solicitação, faça as substituições a seguir:

  • project-id: o ID do projeto;
  • operation-name: o nome da operação

Método HTTP e URL: 

GET https://datastore.googleapis.com/v1/projects/project-id/operations/operation-name

Para enviar a solicitação, expanda uma destas opções:

Você receberá uma resposta JSON semelhante à seguinte:

{
  "name": "projects/project-id/operations/ASA3ODAwMzQxNjIyChp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKLRI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2019-10-08T20:07:28.105236Z",
      "endTime": "2019-10-08T20:07:36.310653Z",
      "operationType": "EXPORT_ENTITIES",
      "state": "SUCCESSFUL"
    },
    "progressEntities": {
      "workCompleted": "21",
      "workEstimated": "21"
    },
    "progressBytes": {
      "workCompleted": "2272",
      "workEstimated": "2065"
    },
    "entityFilter": {},
    "outputUrlPrefix": "gs://bucket-name/2019-10-08T20:07:28_28481"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
    "outputUrl": "gs://bucket-name/2019-10-08T20:07:28_28481/2019-10-08T20:07:28_28481.overall_export_metadata"
  }
}

Como estimar o tempo de conclusão

Conforme sua operação é executada, consulte o valor do campo state para o status geral da operação.

Uma solicitação para o status de uma operação de longa duração retorna as métricas workEstimated e workCompleted. Cada uma dessas métricas é retornada no número de bytes e no número de entidades:

  • workEstimated mostra o número total estimado de bytes e documentos que uma operação processará.

  • workCompleted mostra o número de bytes e documentos processados até o momento. Após a conclusão da operação, o valor mostrará o número total de bytes e documentos que foram realmente processados, o que pode ser maior do que o valor de workEstimated.

Divida workCompleted por workEstimated para ter uma estimativa do progresso aproximada. A estimativa pode ser imprecisa, porque ela depende da coleção de estatísticas em atraso.

Por exemplo, veja o status do progresso de uma operação de exportação:

{
  "operations": [
    {
      "name": "projects/project-id/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

Quando uma operação é concluída, a descrição da operação contém "done": true. Consulte o valor do campo state para ver o resultado da operação. Se o campo done não for definido na resposta, seu valor será false. Não dependa da existência do valor done para operações em andamento.

Cancelar uma operação

Console

É possível cancelar uma operação de exportação ou importação em execução na página Importação/Exportação no modo Datastore do Console do Google Cloud.

Acessar a página "Importar/Exportar"

Na tabela Importações e exportações recentes, as operações em execução incluem o botão Cancelar na coluna Concluído. Clique no botão Cancelar para interromper a operação. O botão muda para uma mensagem Cancelando e para Cancelado quando a operação é completamente interrompida.

gcloud

Use o comando operations cancel para interromper uma operação em andamento:

gcloud datastore operations cancel operation-name

Se você cancelar uma operação em execução, ela não será desfeita. Uma operação de exportação cancelada deixa os documentos já exportados no Cloud Storage e uma operação de importação cancelada deixa as atualizações já feitas no seu banco de dados. Não é possível importar uma exportação parcialmente concluída.

Excluir uma operação

gcloud

Use o comando operations delete para remover uma operação da lista de operações recentes. Esse comando não excluirá arquivos de exportação do Cloud Storage.

gcloud datastore operations delete operation-name

Faturamento e preços para exportações e importações gerenciadas

Você precisa ativar o faturamento do projeto do Google Cloud antes de usar o serviço gerenciado de exportação e importação. As operações de exportação e importação contribuem para seus custos do Google Cloud das seguintes maneiras:

Os custos das operações de exportação e importação não são contabilizados no limite de gastos do App Engine. Essas operações não acionarão alertas de orçamento do Google Cloud até serem concluídas. Da mesma forma, as leituras e gravações executadas durante uma operação de exportação ou importação são aplicadas à sua cota diária apenas após a conclusão.

Como visualizar os custos de exportação e importação

As operações de exportação e importação aplicam o rótulo goog-firestoremanaged:exportimport às operações faturadas. Na página de relatórios do Cloud Billing, é possível usar esse rótulo para visualizar os custos relacionados às operações de importação e exportação:

Acesse o rótulo goog-firestoremanaged no menu de filtros.

Permissões

Para executar operações de exportação e importação, sua conta de usuário e a conta de serviço padrão do projeto exigem as permissões de gerenciamento de identidade e acesso descritas abaixo.

Permissões da conta de usuário

A conta de usuário ou de serviço que inicia a operação requer as permissões datastore.databases.export e datastore.databases.import do IAM. Se você for o proprietário do projeto, sua conta já terá as permissões necessárias. Caso contrário, lembre-se de que os seguintes papéis do IAM concedem as permissões necessárias:

  • Proprietário do repositório de dados
  • Administrador de importação e exportação do Datastore

Você também pode atribuir essas permissões com uma função personalizada.

Um proprietário de projeto pode conceder essas funções seguindo as instruções disponíveis na página Como conceder acesso.

Permissões padrão de contas de serviço

Cada projeto do Google Cloud cria automaticamente uma conta de serviço padrão chamada PROJECT_ID@appspot.gserviceaccount.com. As operações de exportação e importação usam essa conta de serviço para autorizar operações do Cloud Storage.

A conta de serviço padrão do seu projeto requer acesso ao bucket do Cloud Storage usado em uma operação de exportação ou importação. Se o bucket do Cloud Storage estiver no mesmo projeto que o banco de dados do modo Datastore, a conta de serviço padrão terá acesso ao bucket por padrão.

Se o bucket do Cloud Storage estiver em outro projeto, será necessário permitir que a conta de serviço padrão acesse o bucket.

Atribuir papéis à conta de serviço padrão

Use a ferramenta de linha de comando gsutil para atribuir um dos papéis abaixo. Por exemplo, para atribuir o papel de Administrador do Storage à conta de serviço padrão, execute:

gsutil iam ch serviceAccount:[PROJECT_ID]@appspot.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Se preferir, atribua esse papel usando o Console do Cloud.

Operações de exportação

Para operações de exportação que envolvem um bucket em outro projeto, modifique as permissões do bucket para atribuir um dos seguintes papéis do Cloud Storage à conta de serviço padrão do projeto que contém o banco de dados no modo Datastore:

  • Administrador do Storage
  • Administrador de objetos do Storage
  • Gravador de bucket legado do Storage

Também é possível criar um papel personalizado do IAM com permissões um pouco diferentes das contidas nos papéis listados acima:

  • storage.buckets.get
  • storage.objects.create
  • storage.objects.delete
  • storage.objects.list

Operações de importação

Para operações de importação que envolvem um bucket do Cloud Storage em outro projeto, modifique as permissões do bucket para atribuir um dos seguintes papéis do Cloud Storage à conta de serviço padrão do projeto que contém o banco de dados do modo Datastore:

  • Administrador do Storage
  • Leitor de objetos do Storage e Leitor de bucket legado do Storage

Também é possível criar um papel personalizado do IAM com as seguintes permissões:

  • storage.buckets.get
  • storage.objects.get

Conta de serviço padrão desativada ou excluída

Ao desativar ou excluir sua conta de serviço padrão do App Engine, seu aplicativo do App Engine perderá o acesso ao banco de dados do modo Datastore. Se você tiver desativado a conta de serviço do App Engine, poderá reativá-la. Consulte Como ativar uma conta de serviço. Se você excluiu sua conta de serviço do App Engine nos últimos 30 dias, poderá restaurá-la. Consulte Como cancelar a exclusão de uma conta de serviço.

Diferenças em relação aos backups do Datastore Admin

Se você já usou o Datastore Admin Console para backups, observe as seguintes diferenças:

  • As exportações criadas por uma exportação gerenciada não aparecem no Admin Console do Datastore. As exportações e importações gerenciadas são um novo serviço que não compartilha dados com a funcionalidade de backup e restauração do App Engine, que é administrada por meio do Console do Cloud.

  • O serviço de exportação e importação gerenciado não é compatível com os mesmos metadados que o backup de administrador do Datastore e não armazena o status de progresso no banco de dados. Para informações sobre como verificar o progresso das operações de exportação e importação, consulte Como gerenciar operações de longa duração

  • Não é possível ver registros de serviço de operações gerenciadas de exportação e importação.

  • O serviço de importação gerenciada é compatível com versões anteriores dos arquivos de backup do Datastore Admin. É possível importar um arquivo de backup do Datastore Admin usando o serviço de importação gerenciada, mas não é possível importar a saída de uma exportação gerenciada usando o Datastore Admin Console.

Como importar para o BigQuery

Para importar dados de uma exportação gerenciada para o BigQuery, consulte Como carregar dados do serviço de exportação do Datastore.

Não é possível carregar dados no BigQuery sem a especificação de um filtro de entidade. Se você quiser importar dados para o BigQuery, a solicitação de exportação precisará incluir um ou mais nomes de tipo no filtro de entidade.

Limite de colunas do BigQuery

O BigQuery impõe um limite de 10.000 colunas por tabela. As operações de exportação geram um esquema de Tabela do BigQuery para cada tipo. Nesse esquema, cada propriedade única dentro de entidades de tipo se torna uma coluna de esquema.

Se um esquema do BigQuery de mais de 10.000 colunas for ultrapassado, a operação de exportação tentará permanecer abaixo do limite da coluna ao tratar entidades incorporadas como blobs. Se essa conversão elevar o número de colunas no esquema para menos de 10 mil, será possível carregar os dados no BigQuery, mas não será possível consultar as propriedades em entidades incorporadas. Se o número de colunas ainda exceder 10 mil,a operação de exportação não vai gerar um esquema do BigQuery para o tipo, e não será possível carregar seus dados no BigQuery.

Migração do agente de serviço

Agora é possível usar um agente de serviço do Firestore para autorizar operações de importação e exportação em vez da conta de serviço do App Engine. O agente de serviço e a conta de serviço usam as seguintes convenções de nomenclatura:

Agente de serviço do Firestore
service-project_number@gcp-sa-firestore.iam.gserviceaccount.com
Conta de serviço do App Engine
project_id@appspot.gserviceaccount.com

O agente de serviço do Firestore é preferível porque é específico do Firestore. A conta de serviço do App Engine é compartilhada por mais de um serviço.

É possível migrar para o agente de serviço do Firestore usando uma destas técnicas:

É preferível a primeira dessas técnicas porque localiza o escopo do efeito em um único projeto no modo Datastore. A segunda técnica não é preferencial porque migra permissões de bucket existentes do Cloud Storage. No entanto, ele oferece conformidade de segurança no nível da organização.

Migre verificando e atualizando as permissões de bucket do Cloud Storage

O processo de migração tem duas etapas:

  1. Atualize as permissões de bucket do Cloud Storage. Consulte a seção a seguir para mais detalhes.
  2. Confirme a migração para o agente de serviço do Firestore.

Permissões do bucket do agente de serviço

Para qualquer operação de exportação ou importação que use um bucket do Cloud Storage em outro projeto, você precisará conceder permissões do agente de serviço do Firestore para esse bucket. Por exemplo, operações que movem dados para outro projeto precisam acessar um bucket nesse outro projeto. Caso contrário, essas operações falharão após a migração para o agente de serviço do Firestore.

Os fluxos de trabalho de importação e exportação que permanecem no mesmo projeto não exigem alterações nas permissões. Por padrão, o agente de serviço do Firestore pode acessar os buckets no mesmo projeto.

Atualize as permissões de buckets do Cloud Storage de outros projetos para conceder acesso ao agente de serviço service-project_number@gcp-sa-firestore.iam.gserviceaccount.com. Conceda ao agente de serviço o papel Firestore Service Agent.

O papel Firestore Service Agent concede permissões de leitura e gravação para um bucket do Cloud Storage. Se você precisar conceder somente permissões de leitura ou gravação, use um papel personalizado.

O processo de migração descrito na seção a seguir ajuda a identificar buckets do Cloud Storage que podem exigir atualizações de permissão.

Migrar um projeto para o agente de serviço do Firestore

Conclua as etapas a seguir para migrar da conta de serviço do App Engine para o agente de serviço do Firestore. Depois de concluída, a migração não poderá ser desfeita.

  1. Acesse a página Importar/Exportar do Datastore no Console do Google Cloud.

    Acessar a página "Importar/Exportar"

  2. Se o projeto ainda não tiver sido migrado para o agente de serviço do Firestore, você verá um banner descrevendo a migração e o botão Verificar status do bucket. A próxima etapa ajuda a identificar e corrigir possíveis erros de permissão.

    Clique em Verificar status do bucket.

    Será exibido um menu com a opção de concluir a migração e uma lista de buckets do Cloud Storage. Pode levar alguns minutos para que a lista seja carregada.

    Essa lista inclui buckets que foram usados recentemente em operações de importação e exportação, mas que atualmente não têm permissões de leitura e gravação para o agente de serviço do modo Datastore.

  3. Anote o nome principal do agente de serviço do modo Datastore. O nome do agente de serviço é exibido no rótulo Agente de serviço para conceder acesso.

  4. Para qualquer bucket na lista que você usará para operações futuras de importação ou exportação, conclua as etapas a seguir:

    1. Nessa linha da tabela do bucket, clique em Corrigir. A página de permissões de um bucket é aberta em uma nova guia.

    2. Clique em Adicionar.
    3. No campo Novos principais, digite o nome do agente de serviço do Firestore.
    4. No campo Selecionar papel, escolha Agentes de serviço > Agente de serviço do Firestore.
    5. Clique em Save.
    6. Volte para a guia com a página "Importar/Exportar" do modo Datastore.
    7. Repita essas etapas para outros buckets na lista. Certifique-se de visualizar todas as páginas da lista.

  5. Clique em Migrate to Agent Service Agent. Se você ainda tiver buckets com verificações de permissão com falha, confirme sua migração clicando em Migrar.

    Um alerta informa quando a migração é concluída. Não é possível desfazer a migração.

Ver status da migração

Para verificar o status da migração do seu projeto, acesse a página Importar/Exportar no Console do Google Cloud:

Acessar a página "Importar/Exportar"

Procure o principal ao lado do rótulo Conta de serviço utilizada:.

Se o principal for service-project_number@gcp-sa-firestore.iam.gserviceaccount.com, seu projeto já foi migrado para o agente de serviço do Firestore. A migração não pode ser desfeita.

Se o projeto não tiver sido migrado, aparecerá um banner na parte superior da página com o botão Verificar status do bucket. Consulte Migrar para o agente de serviço do Firestore para concluir a migração.

Adicionar uma restrição de política a toda a organização

Defina a seguinte restrição na política da sua organização:

Exigir o agente de serviço do Firestore para importação/exportação (firestore.requireP4SAforImportExport).

Essa restrição requer operações de importação e exportação para usar o agente de serviços do Firestore e autorizar solicitações.

Para definir essa restrição, consulte Como criar e gerenciar políticas da organização.

A aplicação dessa restrição de política organizacional não concede automaticamente as permissões de bucket apropriadas do Cloud Storage para o agente de serviço do Firestore.

Se a restrição criar erros de permissão para qualquer fluxo de trabalho de importação ou exportação, será possível desativá-la para voltar a usar a conta de serviço padrão. Depois de verificar e atualizar as permissões de bucket do Cloud Storage, você poderá ativar a restrição novamente.