Como exportar e importar entidades

Nesta página, você aprende a exportar e importar em entidades do Cloud Firestore no modo Datastore usando o serviço de exportação e importação gerenciada. Esse serviço está disponível por meio da ferramenta de linha de comando gcloud e do Administrador da API Cloud Datastore (REST, RPC).

Com o serviço de exportação e importação gerenciado, você pode recuperar exclusões acidentais de dados e exportá-los para o processamento off-line. Você pode exportar todas as entidades ou apenas tipos específicos delas. Da mesma maneira, você pode importar todos os dados de uma exportação ou apenas tipos específicos. Leve em consideração estes fatores à medida que usa o serviço de exportação e importação gerenciado:

  • O serviço de exportação usa leituras com consistência eventual. Não presuma que uma exportação acontece em um único momento. A exportação pode incluir entidades gravadas após a exportação e excluir entidades gravadas antes de a exportação começar.

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

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

  • Quando uma entidade no banco de dados não for afetada por uma importação, ela permanecerá lá 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 que ele esteja 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 um máximo de 20 solicitações de exportação e importação por minuto para um projeto.

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

Antes de começar

Antes de usar o serviço de exportação e importação gerenciado, você precisa completar as tarefas a seguir.

  1. Certifique-se de que o faturamento esteja ativado para seu projeto do Google Cloud Platform. Somente os projetos do GCP com faturamento ativado podem usar a funcionalidade de exportação e importação. Para mais informações sobre cobrança, consulte Faturamento e preços para importações e exportações.

  2. Crie um intervalo do Cloud Storage para o projeto no mesmo local que seu local do banco de dados do Cloud Firestore no modo Datastore. Como todas as exportações e importações dependem do Cloud Storage, você precisa usar o mesmo local para o intervalo do Cloud Storage e para o banco de dados do Cloud 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 à sua conta de usuário um papel do IAM que conceda a permissão datastore.databases.export para exportar dados ou a permissão datastore.databases.import para importar dados. O papel Cloud Datastore Import Export Admin, por exemplo, concede as duas permissões.

  4. Atribua um papel do IAM do Cloud Storage à conta de usuário que conceda permissões de leitura ou gravação para seu intervalo do Cloud Storage.

Configurar o ambiente

Antes de exportar ou importar dados, é necessário configurar as variáveis de ambiente para a ferramenta gcloud e autenticar usando a conta de usuário.

  1. Defina uma variável de ambiente para o código do projeto do GCP.

    PROJECT_ID="YOUR_PROJECT_ID"
    
  2. Use esta variável para configurar o projeto como a configuração ativa para a ferramenta gcloud.

    gcloud config set project ${PROJECT_ID}
    
  3. Autentique usando a ferramenta gcloud.

    gcloud auth login
    
  4. Defina uma variável de ambiente para seu código de intervalo do Cloud Storage.

    BUCKET="YOUR_BUCKET_NAME[/NAMESPACE_PATH]"
    

    YOUR_BUCKET_NAME é o nome do intervalo do Cloud Storage, e NAMESPACE_PATH é um caminho opcional de namespace do Cloud Storage (ou seja, não é um namespace do modo Datastore). Para mais informações sobre caminhos de namespace do Cloud Storage, consulte Considerações de nome de objeto.

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

Nesta seção, descreveremos como iniciar uma operação de exportação ou importação gerenciada e como verificar o progresso dela.

Como exportar entidades

Use o comando abaixo para exportar todos os tipos no namespace padrão. Adicione a sinalização --async para evitar que a ferramenta gcloud precise aguardar até que a operação seja concluída.

gcloud

gcloud datastore export --namespaces="(default)" gs://${BUCKET}

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "namespaceIds": [""], }, }'

Para exportar um subconjunto específico de tipos e/ou namespaces, forneça um filtro de entidade com valores para tipos e códigos de namespace.

gcloud

gcloud datastore export --kinds="KIND1,KIND2" --namespaces="NAMESPACE1,NAMESPACE2" gs://${BUCKET}

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:export
-d '{ "outputUrlPrefix": "gs://'${BUCKET}'", "entityFilter": { "kinds": ["KIND1", "KIND2", …], "namespaceIds": ["NAMESPACE1", "NAMESPACE2", …], }, }

Como importar entidades

Use o comando abaixo para importar entidades exportadas anteriormente com o serviço de exportação e importação gerenciado. Adicione a sinalização --async para evitar que a ferramenta gcloud precise aguardar até que a operação seja concluída.

gcloud

gcloud datastore import gs://${BUCKET}/[PATH]/[FILE].overall_export_metadata

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "Content-Type: application/json"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}:import
-d '{ "inputUrl": "gs://'${BUCKET}'/[PATH]/[FILE].overall_export_metadata", }'

Você pode determinar o valor a ser usado no local de importação usando a IU do Cloud Storage no console do Google Cloud Platform para visualizar o intervalo ou examinando a saída gcloud datastore export ou ExportEntitiesResponse após a conclusão da exportação. Aqui está um exemplo de valor de um local de importação:

gcloud

gs://${BUCKET}/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata

protocolo

"outputUrl": "gs://'${BUCKET}'/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata",

Exportações ou importações assíncronas

As exportações e importações podem demorar muito tempo. Ao executar uma exportação ou importação, forneça a sinalização --async para evitar que o gcloud aguarde a conclusão da operação.

Depois de iniciar uma operação de exportação ou importação, você pode usar o identificador retornado pela ferramenta gcloud para verificar o status da operação. Por exemplo:

gcloud datastore operations describe ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI

Se você esquecer a sinalização --async, use Ctrl+c para deixar de esperar uma operação. Digitar Ctrl+c não a cancelará.

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

Operações de longa duração são chamadas de método que podem demorar para serem concluídas. Os bancos de dados do modo Datastore criam operações de longa duração quando você exporta ou importa dados.

Por exemplo, quando uma exportação é iniciada, o banco de dados do modo Datastore cria uma operação de longa duração para rastrear o status da exportação. Aqui está a saída do início de uma exportação:

{
  "name": "projects/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
  "metadata": {
    "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
    "common": {
      "startTime": "2017-05-25T23:54:39.583780Z",
      "operationType": "EXPORT_ENTITIES"
    },
    "progressEntities": {},
    "progressBytes": {},
    "entityFilter": {
      "namespaceIds": [
        ""
      ]
    },
    "outputUrlPrefix": "gs://[YOUR_BUCKET_NAME]"
  }
}

O valor do campo name é o código de uma operação de longa duração.

O Cloud Firestore no modo Datastore fornece uma API Admin de operações para verificar o status de operações de longa duração, cancelá-las, excluí-las ou listá-las:

Método Descrição
projects.operations.cancel Cancelar uma operação de longa duração.
projects.operations.delete Excluir uma operação de longa duração.

Observação: a exclusão de uma operação não a cancela.
projects.operations.get Receber o status de uma operação de longa duração.
projects.operations.list Listar operações de longa duração.

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

Para listar operações de longa duração, execute isto:

gcloud

gcloud datastore operations list

Protocolo

curl 
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://datastore.googleapis.com/v1/projects/${PROJECT_ID}/operations

No exemplo de saída, é mostrada uma operação de exportação recentemente concluída. As operações são acessíveis por alguns dias após a conclusão:

{
  "operations": [
    {
      "name": "projects/[YOUR_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://[YOUR_BUCKET_NAME]"
      },
      "done": true,
      "response": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesResponse",
        "outputUrl": "gs://[YOUR_BUCKET_NAME]/2017-05-25T23:54:39_76544/2017-05-25T23:54:39_76544.overall_export_metadata"
      }
    }
  ]
}

Use o valor input_url ao importar entidades.

Como estimar o tempo de conclusão

Uma solicitação para o status de uma operação de longa duração retorna as métricas workEstimated e workCompleted. Cada uma delas é retornada tanto em número de bytes quanto em número de entidades. A métrica workEstimated mostra uma estimativa do número total de bytes e entidades processados por uma operação de acordo com as estatísticas de banco de dados. Já a métrica workCompleted mostra o número de bytes e entidades processados até o momento. Após a conclusão da operação, workCompleted reflete o número total de bytes e entidades que foram realmente processados, o que pode ser maior do que o valor de workEstimated.

Divida workCompleted por workEstimated para uma estimativa de progresso aproximada. A estimativa pode ser imprecisa porque 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/[YOUR_PROJECT_ID]/operations/ASAyMDAwOTEzBxp0bHVhZmVkBxJsYXJ0bmVjc3Utc2Jvai1uaW1kYRQKKhI",
      "metadata": {
        "@type": "type.googleapis.com/google.datastore.admin.v1.ExportEntitiesMetadata",
        ...
        "progressEntities": {
          "workCompleted": "1",
          "workEstimated": "3"
        },
        "progressBytes": {
          "workCompleted": "85",
          "workEstimated": "257"
        },
        ...

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

É necessário ativar o faturamento do projeto do Google Cloud Platform antes de usar o serviço gerenciado de exportação e importação. As operações de exportação e importação são cobradas por leituras e gravações da entidade conforme as taxas listadas em Preços do modo Datastore.

Os custos das operações de exportação e importação não contam para o Limite de gastos do App Engine. Além disso, se você definiu um orçamento do Google Cloud Platform, a operação de exportação ou importação não acionará os alertas até que a operação esteja completa. Da mesma forma, as leituras e gravações executadas durante uma operação de exportação ou importação são aplicadas na sua cota diária após a conclusão da operação.

Para informações sobre faturamento, consulte Suporte de faturamento e pagamentos.

Permissões

Para iniciar operações de exportação e importação, os papéis do IAM precisam conceder as permissões datastore.databases.export e datastore.databases.import. O papel Cloud Datastore Import Export Admin, por exemplo, concede as duas permissões. Da mesma forma, se você estiver usando curl para enviar solicitações REST da linha de comando, será necessário atribuir um papel do IAM que conceda essas permissões à sua conta de usuário. Para mais informações sobre permissões do banco de dados do modo Datastore, consulte Gerenciamento de identidade e acesso (IAM, na sigla em inglês).

Caso você use o aplicativo cron de exemplo, as solicitações usarão a conta de serviço padrão do App Engine do projeto do GCP. É preciso conceder à conta de serviço padrão do App Engine o papel Cloud Datastore Import Export Admin ou outro papel que conceda a permissão datastore.databases.export.

Além disso, para todas as solicitações de exportação, a conta que faz a solicitação e a conta de serviço padrão do App Engine para o projeto do GCP precisam ter um papel do IAM que conceda as seguintes permissões para o intervalo do Cloud Storage:

Nome da permissão Descrição
storage.buckets.get Ler metadados de intervalo, exceto políticas do IAM.
storage.objects.create Adicionar novos objetos a um intervalo.
storage.objects.list Listar objetos em um intervalo. Ler também metadados de objetos, exceto ACLs, durante a listagem.

Para uma lista de papéis do Cloud Storage, consulte Papéis do IAM do Cloud Storage. Por exemplo, os papéis Storage Admin ou Storage Legacy Bucket Writer incluem todas as permissões do Cloud Storage necessárias para realizar uma exportação e podem ser aplicados a um projeto inteiro ou a um intervalo específico. Observe que o papel Storage Object Creator não inclui todas as permissões necessárias do Cloud Storage para realizar uma exportação.

Para todas as solicitações de importação, é preciso que a conta que faz a solicitação e a conta de serviço padrão do projeto do GCP tenham um papel do IAM que conceda as permissões a seguir para o intervalo do Cloud Storage:

Nome da permissão Descrição
storage.objects.get Ler dados e metadados de objeto, exceto ACLs.
storage.objects.list Listar objetos em um intervalo. Ler também metadados de objetos, exceto ACLs, durante a listagem.

O papel Storage Object Viewer concede todas as permissões necessárias para importação.

Diferenças de backups do administrador do Cloud Datastore

Se você já usou o console do administrador do Cloud Datastore para backups, observe as diferenças a seguir:

  • Não há GUI para o serviço de exportação e importação gerenciado.

  • As exportações criadas por uma exportação gerenciada não aparecem no console do administrador do Cloud 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 GCP.

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

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

  • O serviço de importação gerenciado é compatível com os arquivos de backup do administrador do Cloud Datastore. Você pode importar um arquivo de backup do administrador do Cloud Datastore usando o serviço de importação gerenciado, mas não é possível importar a saída de uma exportação gerenciada usando o console do administrador do Cloud Datastore.

Como importar para o BigQuery

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

Limitações

  • Não possível carregar no BigQuery os dados exportados sem a especificação de um filtro de entidade. Para importar dados para o BigQuery, a solicitação de exportação precisa incluir um ou mais nomes de tipo no filtro de entidade.
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Documentação do Cloud Datastore