Exportar e importar entidades

Esta página descreve como exportar e importar entidades do Firestore no modo Datastore através do serviço de exportação e importação gerido. O serviço de exportação e importação gerido está disponível através da Google Cloud consola, da CLI do Google Cloud e da API Datastore Admin (REST, RPC).

Com o serviço de exportação e importação gerido, pode recuperar de eliminações acidentais de dados e exportar dados para processamento offline. Pode exportar todas as entidades ou apenas tipos específicos de entidades. Da mesma forma, pode importar todos os dados de uma exportação ou apenas tipos específicos. À medida que usa o serviço de exportação e importação gerido, tenha em atenção o seguinte:

  • O serviço de exportação usa leituras eventualmente consistentes. Não pode assumir que uma exportação ocorre num único momento. A exportação pode incluir entidades escritas após o início da exportação e excluir entidades escritas antes do início da exportação.

  • Uma exportação não contém índices. Quando importa dados, os índices necessários são automaticamente recompilados através das definições de índice atuais da base de dados. As definições de índice do valor da propriedade por entidade são exportadas e respeitadas durante a importação.

  • As importações não atribuem novos IDs às entidades. As importações usam os IDs que existiam no momento da exportação e substituem qualquer entidade existente com o mesmo ID. Durante uma importação, os IDs são reservados durante o período em que as entidades estão a ser importadas. Esta funcionalidade evita colisões de IDs com novas entidades se as escritas estiverem ativadas enquanto uma importação estiver em execução.

  • Se uma entidade na sua base de dados não for afetada por uma importação, permanece na base de dados após a importação.

  • Os dados exportados de uma base de dados do modo Datastore podem ser importados para outra base de dados do modo Datastore, mesmo que esteja noutro projeto.

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

  • A saída de uma exportação gerida usa o formato de registo LevelDB.

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

  • O nome do ficheiro .overall_export_metadata tem de corresponder ao nome da respetiva pasta principal:

    gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadata

    Se mover ou copiar os ficheiros de saída de uma exportação, mantenha o PARENT_FOLDER_NAME, o conteúdo das subpastas e o nome do ficheiro .overall_export_metadata iguais.

Antes de começar

Antes de poder usar o serviço de exportação e importação gerido, tem de concluir as seguintes tarefas.

  1. Ative a faturação para o seu Google Cloud projeto. Apenas os Google Cloud projetos com a faturação ativada podem usar as funcionalidades de exportação e importação.

  2. Crie um contentor do Cloud Storage na mesma localização que a sua base de dados do Firestore no modo Datastore. Não pode usar um bucket Requester Pays para operações de exportação e importação.

  3. Atribua uma função do IAM à sua conta de utilizador que conceda a autorização datastore.databases.export, se estiver a exportar dados, ou a autorização datastore.databases.import, se estiver a importar dados. A função Datastore Import Export Admin , por exemplo, concede ambas as autorizações.

  4. Se o contentor do Cloud Storage estiver noutro projeto, conceda ao agente de serviço do Firestore acesso ao contentor.

Configure o gcloud para o seu projeto

Se planeia usar o gcloud para iniciar as suas operações de importação e exportação, configure o gcloud e estabeleça ligação ao seu projeto de uma das seguintes formas:

Autorizações

Para executar operações de exportação e importação, a sua conta de utilizador e o agente de serviço do modo Datastore do seu projeto requerem as seguintes autorizações de gestão de identidade e acesso.

Autorizações da conta de utilizador

A conta de utilizador ou a conta de serviço que inicia a operação requer as autorizações de IAM datastore.databases.export e datastore.databases.import. Se for o proprietário do projeto, a sua conta tem as autorizações necessárias. Caso contrário, as seguintes funções de IAM concedem as autorizações necessárias:

  • Proprietário do Datastore
  • Administrador de importação/exportação do Datastore

Também pode atribuir estas autorizações com uma função personalizada.

Um proprietário do projeto pode conceder uma destas funções seguindo os passos em Conceder acesso.

Autorizações do agente de serviço

As operações de exportação e importação usam um agente de serviço do Firestore para autorizar operações do Cloud Storage. O agente de serviço do Firestore usa a seguinte convenção de nomenclatura:

Agente de serviço do Firestore
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com

Para saber mais sobre os agentes de serviços, consulte o artigo Agentes de serviços.

O agente de serviço do Firestore requer acesso ao contentor do Cloud Storage usado numa operação de exportação ou importação. Se o seu contentor do Cloud Storage estiver no mesmo projeto que a sua base de dados do Firestore, o agente de serviço do Firestore pode aceder ao contentor por predefinição.

Se o contentor do Cloud Storage estiver noutro projeto, tem de conceder ao agente de serviço do Firestore acesso ao contentor do Cloud Storage.

Atribua funções ao agente do serviço

Pode usar a ferramenta de linha de comandos gsutil para atribuir uma das funções abaixo. Por exemplo, para atribuir a função de administrador do armazenamento ao agente de serviço do Firestore, execute o seguinte comando:

gsutil iam ch serviceAccount:service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com:roles/storage.admin \
    gs://[BUCKET_NAME]

Substitua PROJECT_NUMBER pelo número do seu projeto, que é usado para dar um nome ao agente do serviço do Firestore. Para ver o nome do agente do serviço, consulte o artigo Veja o nome do agente do serviço.

Em alternativa, pode atribuir esta função através da Google Cloud consola.

Veja o nome do agente do serviço

Pode ver a conta que as suas operações de importação e exportação usam para autorizar pedidos a partir da página Importar/Exportar na Google Cloud consola. Também pode ver se a sua base de dados usa o agente de serviço do Firestore ou a conta de serviço do App Engine antiga.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

  4. Veja a conta de autorização junto à etiqueta Trabalhos de importação/exportação executados como.

Operações de exportação

Para operações de exportação que envolvam um contentor noutro projeto, modifique as autorizações do contentor para atribuir uma das seguintes funções de gestão de identidades e acessos ao agente de serviço do modo Datastore do projeto que contém a sua base de dados do modo Datastore:

  • Administrador de armazenamento
  • Proprietário (função básica)

Também pode criar uma função personalizada de IAM com autorizações ligeiramente diferentes das contidas nas funções indicadas anteriormente:

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

Operações de importação

Para operações de importação que envolvam um contentor do Cloud Storage noutro projeto, modifique as autorizações do contentor para atribuir uma das seguintes funções do Cloud Storage ao agente do serviço do modo Datastore do projeto que contém a sua base de dados do modo Datastore:

  • Administrador de armazenamento
  • Storage Object Viewer e Storage Legacy Bucket Reader

Também pode criar uma função personalizada do IAM com as seguintes autorizações:

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

Iniciar operações de exportação e importação geridas

Esta secção descreve como iniciar uma operação de exportação ou importação gerida.

Exportar todas as entidades

Consola

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  1. No menu de navegação, clique em Importar/exportar.
  2. Clique em Exportar.
  3. Defina o campo Namespace como All Namespaces e defina o campo Kind como All Kinds.
  4. Abaixo de Destino, introduza o nome do seu contentor do Cloud Storage.
  5. Clique em Exportar.

A consola regressa à página Importar/Exportar. Um alerta comunica o êxito ou a falha do seu pedido de exportação gerido.

gcloud

Use o comando gcloud firestore export para exportar todas as entidades na sua base de dados.

 gcloud firestore export gs://bucket-name --async --database=DATABASE

onde bucket-name é o nome do seu contentor do Cloud Storage e um prefixo opcional, por exemplo, bucket-name/datastore-exports/export-name. Não pode voltar a usar o mesmo prefixo para outra operação de exportação. Se não fornecer um prefixo de ficheiro, o serviço de exportação gerido cria um com base na hora atual.

Use a flag [--async][async-flag] para impedir que gcloud aguarde pela conclusão da operação. Se omitir a flag --async, pode escrever Ctrl+c para parar de aguardar uma operação. Esta ação não cancela a operação.

Defina a flag --database para o nome da base de dados a partir da qual quer exportar as entidades. Para a base de dados predefinida, use --database='(default)'.

descanso

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

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

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve 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 verificar para saber se foi concluída.

Exportar tipos ou espaços de nomes específicos

Para exportar um subconjunto específico de tipos e/ou espaços de nomes, forneça um filtro de entidades com valores para tipos e IDs de espaços de nomes. Cada pedido está limitado a 100 combinações de filtros de entidades, em que cada combinação de tipo filtrado e espaço de nomes conta como um filtro separado para este limite.

Consola

Na consola, pode selecionar todos os tipos ou um tipo específico. Da mesma forma, pode selecionar todos os namespaces ou um namespace específico.

Em alternativa, use gcloud para especificar uma lista de espaços de nomes e tipos a exportar.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

  4. Clique em Exportar.

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

  6. Defina o campo Kind como All Kinds ou com o nome de um tipo.

  7. Em Destino, introduza o nome do seu contentor do Cloud Storage.

  8. Clique em Exportar.

A consola regressa à página Importar/Exportar. Um alerta comunica o êxito ou a falha do seu pedido de exportação gerido.

gcloud

  gcloud firestore export --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name \
  --async \
  --database=DATABASE

onde bucket-name é o nome do seu contentor do Cloud Storage e um prefixo opcional, por exemplo, bucket-name/datastore-exports/export-name. Não pode voltar a usar o mesmo prefixo para outra operação de exportação. Se não fornecer um prefixo de ficheiro, o serviço de exportação gerido cria um com base na hora atual.

Use a flag [--async][async-flag] para impedir que gcloud aguarde pela conclusão da operação. Se omitir a flag --async, pode escrever Ctrl+c para parar de aguardar uma operação. Esta ação não cancela a operação.

Defina a flag --database para o nome da base de dados a partir da qual quer exportar tipos ou espaços de nomes específicos. Para a base de dados predefinida, use --database='(default)'.

descanso

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do seu projeto
  • bucket-name: o nome do seu contentor do Cloud Storage
  • kind: o tipo de entidade
  • namespace: o ID do espaço de nomes (use "" para o ID do espaço de nomes predefinido)

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve 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 verificar para saber se foi concluída.

Ficheiros de metadados

Uma operação de exportação cria um ficheiro de metadados para cada par de tipo de espaço de nomes especificado. Normalmente, os ficheiros de metadados são denominados NAMESPACE_NAME_KIND_NAME.export_metadata. No entanto, se um namespace ou um tipo criar um nome de objeto do Cloud Storage inválido, o ficheiro recebe o nome export[NUM].export_metadata.

Os ficheiros de metadados são buffers de protocolo e podem ser descodificados com o protoc compilador de protocolo. Por exemplo, pode descodificar um ficheiro de metadados para determinar o espaço de nomes e os tipos que os ficheiros de exportação contêm:

protoc --decode_raw < export0.export_metadata

Importar todas as entidades

Consola

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

  4. Clique em Importar.

  5. No campo File, clique em Procurar e selecione um ficheiro .overall_export_metadata.

    Certifique-se de que o ficheiro .overall_export_metadata não é movido da localização predefinida.

  6. Defina o campo Namespace como All Namespaces e defina o campo Kind como All Kinds.

  7. Clique em Importar.

A consola regressa à página Importar/Exportar. Um alerta comunica o êxito ou a falha do seu pedido de importação gerida.

gcloud

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

gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \
--async \
--database=DATABASE

onde bucket-name/file-path/file-name é o caminho para o ficheiro overall_export_metadata no seu contentor do Cloud Storage.

Use a flag [--async][async-flag] para impedir que gcloud aguarde pela conclusão da operação. Se omitir a flag --async, pode escrever Ctrl+c para parar de aguardar uma operação. Esta ação não cancela a operação.

Defina a flag --database para o nome da base de dados onde quer importar todas as entidades. Para a base de dados predefinida, use --database='(default)'.

descanso

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do seu projeto
  • bucket-name: o nome do seu contentor 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 do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve 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 verificar para saber se foi concluída.

Localizar o seu ficheiro overall_export_metadata

Pode determinar o valor a usar para a localização de importação através do navegador do Cloud Storage na Google Cloud consola:

Abra o navegador de armazenamento na nuvem

Também pode listar e descrever operações concluídas. O campo outputURL mostra o nome do ficheiro overall_export_metadata:

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

Importar tipos ou espaços de nomes específicos

Para importar um subconjunto específico de tipos e/ou espaços de nomes, forneça um filtro de entidades com valores para tipos e IDs de espaços de nomes.

Só pode especificar tipos e espaços de nomes se os ficheiros de exportação tiverem sido criados com um filtro de entidades. Não pode importar um subconjunto de tipos e espaços de nomes de uma exportação de todas as entidades.

Consola

Na consola, pode selecionar todos os tipos ou um tipo específico. Da mesma forma, pode selecionar todos os namespaces ou um namespace específico.

Em alternativa, use gcloud para especificar uma lista de espaços de nomes e tipos a importar.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

  4. Clique em Importar.

  5. No campo File, clique em Procurar e selecione um ficheiro .overall_export_metadata.

    Certifique-se de que importa o ficheiro .overall_export_metadata e não um ficheiro .export_metadata.

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

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

  8. Clique em Importar.

A consola regressa à página Importar/Exportar. Um alerta comunica o êxito ou a falha do seu pedido de importação gerida.

gcloud

  gcloud firestore import --collection-ids="KIND1,KIND2" \
  --namespaces="(default),NAMESPACE2" \
  gs://bucket-name/file-path/file-nameoverall_export_metadata \
  --async \
  --database=DATABASE

onde bucket-name/file-path/file-name é o caminho para o ficheiro overall_export_metadata no seu contentor do Cloud Storage.

Use a flag [--async][async-flag] para impedir que gcloud aguarde pela conclusão da operação. Se omitir a flag --async, pode escrever Ctrl+c para parar de aguardar uma operação. Esta ação não cancela a operação.

Defina a flag --database para o nome da base de dados onde quer importar os tipos ou os espaços de nomes específicos. Para a base de dados predefinida, use --database='(default)'.

descanso

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do seu projeto
  • bucket-name: o nome do seu contentor 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 espaço de nomes (use "" para o ID do espaço de nomes predefinido)

Método HTTP e URL: 

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

Corpo JSON do pedido: 

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

Para enviar o seu pedido, expanda uma destas opções:

Deve 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 verificar para saber se foi concluída.

Exporte e importe dados de PITR

Pode exportar a sua base de dados para o Cloud Storage a partir de [dados PITR][pitr]. Pode exportar dados PITR cuja data/hora seja uma data/hora de um minuto inteiro nos últimos sete dias, mas não antes de earliestVersionTime. Se os dados já não existirem na data/hora especificada, a operação de exportação falha.

A operação de exportação PITR suporta todos os filtros, incluindo a exportação de todos os documentos e a exportação de coleções específicas.

Tenha em atenção os seguintes pontos antes de exportar dados PITR:

  • Especifique a data/hora no formato RFC 3339. Por exemplo, 2023-05-26T10:20:00.00Z.
  • Certifique-se de que a data/hora especificada é uma data/hora de um minuto inteiro nos últimos sete dias, mas não anterior a earliestVersionTime. Se os dados já não existirem na data/hora especificada, é gerado um erro.
  • Não lhe é cobrado um valor por uma exportação PITR falhada.

Consola

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados
  2. Selecione uma base de dados na lista de bases de dados.
  3. No menu de navegação, clique em Importar/exportar.
  4. Clique em Exportar.
  5. Escolha um espaço de nomes para exportar
  6. Selecione os tipos a exportar.

  7. Na secção Escolha o estado da base de dados a exportar, selecione Exportar a partir de um ponto anterior no tempo.

    Selecione uma hora do instantâneo a usar para a exportação

  8. Na secção Destino, introduza o nome de um contentor do Cloud Storage ou use o botão Procurar para selecionar um contentor.

  9. Clique em Exportar.

    A consola regressa à página Importar/Exportar. Se a operação for iniciada com êxito, a página adiciona uma entrada à página de importações e exportações recentes. Em caso de falha, a página apresenta uma mensagem de erro.

gcloud

Pode exportar a sua base de dados para o Cloud Storage a partir de dados PITR através do comando gcloud firestore export. A operação de exportação PITR suporta todos os filtros, incluindo a exportação de todas as entidades e a exportação de tipos ou espaços de nomes específicos.

Exporte a base de dados, especificando o parâmetro snapshot-time para uma data/hora de recuperação. Execute o seguinte comando para exportar a base de dados para o seu contentor.

gcloud firestore export gs://[BUCKET_NAME_PATH] \
          --snapshot-time=[PITR_TIMESTAMP] \
          --collection-ids=[COLLECTION_IDS] \
          --namespace-ids=[NAMESPACE_IDS]

Onde PITR_TIMESTAMP é uma data/hora de PITR com granularidade de minutos, por exemplo, 2023-05-26T10:20:00.00Z.

Importe transformações

Quando importa entidades de outro projeto, tenha em atenção que as chaves de entidades incluem o ID do projeto. Uma operação de importação atualiza as chaves das entidades e as propriedades de referência das chaves nos dados de importação com o ID do projeto de destino. Se esta atualização aumentar os tamanhos das entidades, pode causar erros do tipo "entity is too big" (a entidade é demasiado grande) ou "index entries too large" (as entradas de índice são demasiado grandes) para operações de importação.

Para evitar qualquer um dos erros, importe para um projeto de destino com um ID do projeto mais curto. Isto não afeta as operações de importação com dados do mesmo projeto.

Gerir operações de longa duração

As operações de importação e exportação geridas são operações de longa duração. Estas chamadas de método podem demorar um período considerável a serem concluídas.

Depois de iniciar uma operação de exportação ou importação, o modo Datastore atribui um nome exclusivo à operação. Pode usar o nome da operação para eliminar, cancelar ou verificar o estado da operação.

Os nomes das operações têm o prefixo projects/[PROJECT_ID]/databases/(default)/operations/, por exemplo:

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

Pode omitir o prefixo quando especificar um nome de operação para comandos gcloud.

Listar todas as operações de longa duração

Pode ver as operações em curso e as operações concluídas recentemente das seguintes formas. As operações são apresentadas durante alguns dias após a conclusão:

Consola

Pode ver uma lista das operações de longa duração na página Importar/Exportar da Google Cloud consola.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em 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 do pedido, faça as seguintes substituições:

  • project-id: o ID do seu projeto

Método HTTP e URL: 

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

Para enviar o seu pedido, expanda uma destas opções:

Veja 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"
      }
    }
  ]
}

Verifique o estado da operação

Para ver o estado de uma operação de execução longa:

Consola

Pode ver uma lista das operações de exportação e importação mais recentes na página Importar/Exportar da Google Cloud consola.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

gcloud

Use o comando operations describe para mostrar o estado de uma operação de execução longa.

gcloud datastore operations describe operation-name

descanso

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • project-id: o ID do seu 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 o seu pedido, expanda uma destas opções:

Deve 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"
  }
}

Estimar o tempo de conclusão

À medida que a operação é executada, veja o valor do campo state para o estado geral da operação.

Um pedido do estado de uma operação de longa duração devolve as métricas workEstimated e workCompleted. Cada uma destas métricas é devolvida 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 vai processar. O modo Datastore pode omitir esta métrica se não conseguir fazer uma estimativa.

  • workCompleted mostra o número de bytes e documentos processados até agora. Após a conclusão da operação, o valor mostra o número total de bytes e documentos que foram efetivamente processados, o que pode ser superior ao valor de workEstimated.

Divida workCompleted por workEstimated para uma estimativa aproximada do progresso. Esta estimativa pode ser imprecisa, uma vez que depende da recolha de estatísticas atrasadas.

Por exemplo, segue-se o estado 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 estiver definido na resposta, o respetivo valor é false. Não dependa da existência do valor done para operações em curso.

Cancele uma operação

Consola

Pode cancelar uma operação de exportação ou importação em execução na página Importar/Exportar da Google Cloud consola.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

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

gcloud

Use o comando operations cancel para parar uma operação em curso:

gcloud datastore operations cancel operation-name

O cancelamento de uma operação em execução não anula a operação. Uma operação de exportação cancelada deixa os documentos já exportados no Cloud Storage, e uma operação de importação cancelada deixa no lugar as atualizações já feitas à sua base de dados. Não pode importar uma exportação concluída parcialmente.

Elimine uma operação

gcloud

Use o comando operations delete para remover uma operação da lista de operações recentes. Este comando não elimina os ficheiros de exportação do Cloud Storage.

gcloud datastore operations delete operation-name

Faturação e preços para exportações e importações geridas

Tem de ativar a faturação para o seu projeto Google Cloud antes de usar o serviço de exportação e importação gerido. As operações de exportação e importação contribuem para os seus Google Cloud custos das seguintes formas:

  • As leituras e as escritas de entidades realizadas por operações de exportação e importação contam para os seus custos do Firestore no modo Datastore. As operações de exportação incorrem numa operação de leitura por entidade exportada. As operações de importação incorrem numa operação de escrita por entidade importada.
  • Os ficheiros de saída armazenados no Cloud Storage são contabilizados nos seus custos de armazenamento de dados do Cloud Storage.

As operações de exportação ou importação não acionam alertas de Google Cloud orçamento até à conclusão. Da mesma forma, as leituras e as escritas realizadas durante uma operação de exportação ou importação são aplicadas à sua quota diária após a conclusão da operação.

Ver custos de exportação e importação

As operações de exportação e importação aplicam a etiqueta goog-firestoremanaged:exportimport às operações faturadas. Na página de relatórios do Cloud Billing, pode usar esta etiqueta para ver os custos relacionados com operações de importação e exportação:

Aceda à etiqueta goog-firestoremanaged no menu de filtros.

Diferenças em relação às cópias de segurança do Datastore Admin

Se usou anteriormente a consola de administração do Datastore para cópias de segurança, deve ter em atenção as seguintes diferenças:

  • As exportações criadas por uma exportação gerida não são apresentadas na consola do administrador do Datastore. As exportações e importações geridas são um novo serviço que não partilha dados com a funcionalidade de cópia de segurança e restauro do App Engine, que é administrada através da Google Cloud consola.

  • O serviço de exportação e importação gerido não suporta os mesmos metadados que a cópia de segurança do administrador do Datastore e não armazena o estado de progresso na sua base de dados. Para obter informações sobre como verificar o progresso das operações de exportação e importação, consulte o artigo Gerir operações de longa duração

  • Não pode ver os registos de serviço das operações de exportação e importação geridas.

  • O serviço de importação gerido é retrocompatível com ficheiros de cópia de segurança do Datastore Admin. Pode importar um ficheiro de cópia de segurança do Datastore Admin através do serviço de importação gerido, mas não pode importar o resultado de uma exportação gerida através da consola do Datastore Admin.

Importar para o BigQuery

Para importar dados de uma exportação gerida para o BigQuery, consulte o artigo Carregar dados do serviço de exportação do Datastore.

Não é possível carregar no BigQuery dados exportados sem especificar um filtro de entidades. Se quiser importar dados para o BigQuery, o seu pedido de exportação tem de incluir um ou mais nomes de tipos no filtro de entidades.

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. Neste esquema, cada propriedade única nas entidades de um tipo torna-se uma coluna do esquema.

Se o esquema do BigQuery de um tipo exceder as 10 000 colunas, a operação de exportação tenta manter-se abaixo do limite de colunas tratando as entidades incorporadas como blobs. Se esta conversão fizer com que o número de colunas no esquema seja inferior a 10 000, pode carregar os dados para o BigQuery, mas não pode consultar as propriedades nas entidades incorporadas. Se o número de colunas continuar a exceder 10 000, a operação de exportação não gera um esquema do BigQuery para o tipo e não pode carregar os respetivos dados para o BigQuery.

Migração de agentes de serviço

O Firestore usa um agente do serviço do Firestore para autorizar operações de importação e exportação em vez de usar a conta de serviço do App Engine. O agente do 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

Anteriormente, o Firestore usava a conta de serviço predefinida do App Engine em vez do agente de serviço do Firestore. Se a sua base de dados continuar a usar a conta de serviço do App Engine para importar ou exportar dados, recomendamos que siga as instruções nesta secção para migrar para a utilização do agente de serviço do Firestore.

Conta de serviço do App Engine
PROJECT_ID@appspot.gserviceaccount.com

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

Ver conta de autorização

Pode ver que conta as suas operações de importação e exportação usam para autorizar pedidos a partir da página Importar/Exportar na Google Cloud consola. Também pode ver se a sua base de dados já usa o agente do serviço Firestore.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

  4. Veja a conta de autorização junto à etiqueta Trabalhos de importação/exportação executados como.

Se o seu projeto não usar o agente de serviço do Firestore, pode migrar para o agente de serviço do Firestore usando uma destas técnicas:

A primeira destas técnicas é preferível porque localiza o âmbito do efeito num único projeto do modo Datastore. A segunda técnica não é preferível porque não migra as autorizações do contentor do Cloud Storage existente. No entanto, oferece conformidade de segurança ao nível da organização.

Migre verificando e atualizando as autorizações do contentor do Cloud Storage

O processo de migração tem dois passos:

  1. Atualize as autorizações do contentor do Cloud Storage. Consulte a secção seguinte para ver detalhes.
  2. Confirme a migração para o agente do serviço Firestore.

Autorizações de contentores de agentes de serviço

Para quaisquer operações de exportação ou importação que usem um contentor do Cloud Storage noutro projeto, tem de conceder autorizações do agente de serviço do Firestore para esse contentor. Por exemplo, as operações que movem dados para outro projeto têm de aceder a um contentor nesse outro projeto. Caso contrário, estas operações falham após a migração para o agente do serviço Firestore.

Os fluxos de trabalho de importação e exportação que permanecem no mesmo projeto não requerem alterações às autorizações. O agente do serviço Firestore pode aceder aos contentores no mesmo projeto por predefinição.

Atualize as autorizações dos contentores do Cloud Storage de outros projetos para conceder acesso ao service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com agente do serviço. Conceda ao agente do serviço a função de Firestore Service Agent.

A função Firestore Service Agent concede autorizações de leitura e escrita para um contentor do Cloud Storage. Se precisar de conceder apenas autorizações de leitura ou apenas de escrita, use uma função personalizada.

O processo de migração descrito na secção seguinte ajuda a identificar contentores do Cloud Storage que podem exigir atualizações de autorizações.

Migre um projeto para o agente do serviço Firestore

Conclua os passos seguintes para migrar da conta de serviço do App Engine para o agente de serviço do Firestore. Uma vez concluída, a migração não pode ser revertida.

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

  4. Se o seu projeto ainda não tiver sido migrado para o agente do serviço Firestore, é apresentada uma faixa a descrever a migração e um botão Verificar estado do contentor. O passo seguinte ajuda a identificar e corrigir potenciais erros de autorização.

    Clique em Verificar estado do contentor.

    É apresentado um menu com a opção para concluir a migração e uma lista de contentores de armazenamento na nuvem. O carregamento da lista pode demorar alguns minutos.

    Esta lista inclui contentores que foram usados recentemente em operações de importação e exportação, mas que atualmente não concedem autorizações de leitura e escrita ao agente do serviço do modo Datastore.

  5. Tome nota do nome principal do agente do serviço do modo Datastore do seu projeto. O nome do agente do serviço é apresentado por baixo da etiqueta Agente do serviço ao qual conceder acesso.

  6. Para qualquer contentor na lista que vai usar para futuras operações de importação ou exportação, conclua os seguintes passos:

    1. Na linha da tabela deste conjunto, clique em Corrigir. Esta ação abre a página de autorizações desse contentor num novo separador.

    2. Clique em Adicionar.
    3. No campo Novos membros, introduza o nome do agente de serviço do Firestore.
    4. No campo Selecionar uma função, selecione Agentes de serviço > Agente de serviço do Firestore.
    5. Clique em Guardar.
    6. Volte ao separador com a página Importar/Exportar do modo Datastore.
    7. Repita estes passos para outros contentores na lista. Certifique-se de que vê todas as páginas da lista.

  7. Clique em Migrar para o agente do serviço do Firestore. Se ainda tiver contentores com verificações de autorizações com falhas, tem de confirmar a migração clicando em Migrar.

    É apresentado um alerta quando a migração estiver concluída. Não é possível anular a migração.

Veja o estado da migração

Para verificar o estado da migração do seu projeto:

  1. Na Google Cloud consola, aceda à página Bases de dados.

    Aceda a Bases de dados

  2. Selecione a base de dados necessária na lista de bases de dados.

  3. No menu de navegação, clique em Importar/exportar.

  4. Procure o principal junto à etiqueta Tarefas de importação/exportação executadas como.

    Se o principal for service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, o seu projeto já foi migrado para o agente do serviço Firestore. Não é possível anular a migração.

    Se o projeto não tiver sido migrado, é apresentada uma faixa na parte superior da página com um botão Verificar estado do contentor. Consulte o artigo Migre para o agente do serviço Firestore para concluir a migração.

Adicione uma restrição de política ao nível da organização

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

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

    Esta restrição requer que as operações de importação e exportação usem o agente do serviço do Firestore para autorizar pedidos. Para definir esta restrição, consulte o artigo Criar e gerir políticas da organização .

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

Se a restrição criar erros de autorização para fluxos de trabalho de importação ou exportação, pode desativá-la para voltar a usar a conta de serviço predefinida. Depois de verificar e atualizar as autorizações do contentor do Cloud Storage, pode ativar novamente a restrição.