Nesta página, descrevemos como exportar e importar as entidades do Firestore em modo Datastore usando o serviço de exportação e importação gerenciado. O serviço de exportação e importação gerenciadas está disponível no console do Google Cloud, na Google Cloud CLI e na API Datastore Admin (REST, RPC).
Com o serviço de exportação e importação gerenciado, é possível 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 IDs às entidades. As importações usam os IDs que existiam no momento da exportação e substituem qualquer entidade atual com o mesmo ID. Durante uma importação, os IDs são reservados enquanto as entidades estão sendo importadas. Esse recurso evita conflitos de IDs 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. Para cada solicitação, o serviço limita o número de combinações de filtros de entidade 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.
O nome do arquivo
.overall_export_metadataprecisa ser igual ao nome da pasta mãe:gs://BUCKET_NAME/OPTIONAL_NAMESPACE_PATH/PARENT_FOLDER_NAME/PARENT_FOLDER_NAME.overall_export_metadataSe você mover ou copiar os arquivos de saída de uma exportação, mantenha os
PARENT_FOLDER_NAME, o conteúdo das subpastas e o nome do arquivo.overall_export_metadataiguais.
Antes de começar
Antes de usar o serviço de exportação e importação gerenciado, você precisa completar as tarefas a seguir.
Ative o faturamento para seu projeto do Google Cloud. Somente projetos do Google Cloud com faturamento ativado podem usar os recursos de exportação e importação.
Crie um bucket do Cloud Storage no mesmo local que seu banco de dados do Firestore em modo Datastore. Não é possível usar um bucket de pagamentos do solicitante para operações de exportação e importação.
Atribua um papel de IAM à sua conta de usuário que conceda a permissão
datastore.databases.export, se você estiver exportando dados, ou a permissãodatastore.databases.import, se estiver importando dados. O papelDatastore Import Export Admin, por exemplo, concede as duas permissões.Se o bucket do Cloud Storage estiver em outro projeto, conceda ao agente de serviço do Firestore acesso ao bucket.
Configurar gcloud para seu projeto
Se você planeja usar gcloud para iniciar suas operações de importação e exportação, configure gcloud e conecte-se a seu projeto de uma das seguintes maneiras:
Acesse
gcloudno console do Google Cloud usando o Cloud Shell.Configure a CLI gcloud para usar seu projeto atual:
gcloud config set project project-id
Permissões
Para executar operações de exportação e importação, sua conta de usuário e o agente de serviço do modo Datastore do seu projeto exigem as seguintes permissões do Identity and Access Management.
Permissões da conta de usuário
A conta de usuário ou a conta de serviço que iniciou a operação requer as permissões datastore.databases.export e datastore.databases.import do IAM. Se você é o proprietário do projeto, isso significa que sua conta tem as permissões necessárias. Caso contrário, os seguintes papéis do IAM concedem as permissões necessárias:
- Proprietário do Datastore
- Administrador de importação e exportação do Datastore
Você também pode atribuir essas permissões com um papel personalizado.
Um proprietário de projeto pode conceder essas funções seguindo as instruções disponíveis na página Como conceder acesso.
Permissõ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ço, consulte Agentes de serviço.
O agente de serviço do Firestore 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 Firestore, o agente de serviço do Firestore poderá acessar o bucket por padrão.
Se o bucket do Cloud Storage estiver em outro projeto, será necessário conceder ao agente de serviço do Firestore acesso ao bucket.
Atribuir papéis ao agente de serviç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 ao agente de serviço do Firestore, execute o seguinte:
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 projeto, que é usado para nomear o agente de serviço do Firestore. Para ver o nome do agente de serviço, acesse Consultar o nome do agente de serviço.
Também é possível atribuir esse papel usando o console do Google Cloud.
Consultar o nome do agente de serviço
É possível consultar a conta que suas operações de importação e exportação usam para autorizar solicitações na página Importar/Exportar no console do Google Cloud Platform. Também é possível verificar se o banco de dados usa o agente de serviço do Firestore ou a conta de serviço legada do App Engine.
-
No Console do Google Cloud, acesse a página Bancos de Dados.
-
Selecione o banco de dados necessário na lista de bancos de dados.
-
No menu de navegação, clique em Importar/Exportar.
- Veja a conta de autorização ao lado do rótulo Importar/exportar jobs executados como.
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 de gerenciamento de identidade e acesso ao agente de serviço do modo Datastore do projeto que contém o banco de dados do modo Datastore:
- Administrador de armazenamento
- Proprietário (papel básico)
Também é possível criar um papel personalizado do IAM com permissões um pouco diferentes daquelas contidas nos papéis listados anteriormente:
storage.buckets.getstorage.objects.createstorage.objects.deletestorage.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 ao agente do serviço do modo Datastore do projeto que contém o banco de dados do modo Datastore:
- Administrador de armazenamento
- Leitor de objetos 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.getstorage.objects.get
Como iniciar operações de exportação e importação gerenciadas
Nesta seção, descrevemos como iniciar uma operação de exportação ou importação gerenciada.
Como exportar todas as entidades
Console
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
- No menu de navegação, clique em Importar/Exportar.
- Clique em Exportar.
- Defina o campo Namespace como
All Namespacese defina o campo Tipo comoAll Kinds. - Abaixo de Destino, insira o nome do seu bucket do Cloud Storage.
- Clique em Exportar.
O console retorna à página Importar/Exportar. Um alerta informará sucesso ou falha da sua solicitação de exportação gerenciada.
gcloud
Use o comando gcloud firestore export
para exportar todas as entidades no seu banco de dados.
gcloud firestore export gs://bucket-name --async --database=DATABASE
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 gerenciada criará um com base no horário atual.
Use a flag [--async][flag-assíncrono] para evitar que gcloud aguarde a
conclusão da operação. Se você omitir a flag --async, digite
Ctrl+c para não aguardar uma operação. Isso não cancelará a operação.
Defina a flag --database como o nome do banco de dados de onde você quer exportar as entidades. Para o banco de dados padrão, use --database='(default)'.
rest
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: ID do projeto
- bucket-name: 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 a esta:
{
"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"
}
}
Como 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 e namespace filtrado 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.
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em Importar/Exportar.
Clique em Exportar.
Defina o campo Namespace como
All Namespacesou o nome de um dos seus namespaces.Defina o campo Tipo como
All Kindsou como o nome de um tipo.Em Destino, insira o nome do bucket do Cloud Storage.
Clique em Exportar.
O console retorna à página Importar/Exportar. Um alerta informará sucesso ou falha da sua solicitação de exportação gerenciada.
gcloud
gcloud firestore export --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name \ --async \ --database=DATABASE
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 gerenciada criará um com base no horário atual.
Use a flag [--async][flag-assíncrono] para evitar que gcloud aguarde a
conclusão da operação. Se você omitir a flag --async, digite
Ctrl+c para não aguardar uma operação. Isso não cancelará a operação.
Defina a flag --database como o nome do banco de dados de onde você quer exportar tipos ou namespaces específicos. Para o banco de dados padrão, use --database='(default)'.
rest
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: ID do projeto
- bucket-name: 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 a esta:
{
"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"
}
}
Arquivos de metadados
Uma operação de exportação cria um arquivo de metadados para cada par 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á nomeado como 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
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em Importar/Exportar.
Clique em Importar.
No campo
File, clique em Procurar e selecione um arquivo.overall_export_metadata.Verifique se o arquivo
.overall_export_metadatanão foi movido do local padrão.Defina o campo Namespace como
All Namespacese defina o campo Tipo comoAll Kinds.Clique em Importar.
O console retorna à página Importar/Exportar. Um alerta informará sucesso ou falha da sua solicitação de importação gerenciada.
gcloud
Use o comando gcloud firestore import para importar todas as entidades que foram exportadas anteriormente com o serviço de exportação gerenciado.
gcloud firestore import gs://bucket-name/file-path/file-name.overall_export_metadata \ --async \ --database=DATABASE
em que bucket-name/file-path/file-name é o caminho para o arquivo overall_export_metadata no bucket do Cloud Storage.
Use a flag [--async][flag-assíncrono] para evitar que gcloud aguarde a
conclusão da operação. Se você omitir a flag --async, digite
Ctrl+c para não aguardar uma operação. Isso não cancelará a operação.
Defina a flag --database como o nome do banco de dados em que você quer importar todas as entidades. Para o banco de dados padrão, use --database='(default)'.
rest
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: ID do projeto
- bucket-name: nome do bucket do Cloud Storage
- object-name: 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 a esta:
{
"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"
}
}
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:
Abrir 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.
Você só poderá especificar tipos e namespaces se os arquivos de exportação tiverem sido criados com o uso de 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.
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em Importar/Exportar.
Clique em Importar.
No campo
File, clique em Procurar e selecione um arquivo.overall_export_metadata.Importe o arquivo
.overall_export_metadata, não um arquivo.export_metadata.Defina o campo Namespace como
All Namespacesou como um namespace específico.Defina o campo Tipo como
All Kindsou como um tipo específico.Clique em Importar.
O console retorna à página Importar/Exportar. Um alerta informará sucesso ou falha da sua solicitação de importação gerenciada.
gcloud
gcloud firestore import --collection-ids="KIND1,KIND2" \ --namespaces="(default),NAMESPACE2" \ gs://bucket-name/file-path/file-nameoverall_export_metadata \ --async \ --database=DATABASE
em que bucket-name/file-path/file-name é o caminho para o arquivo overall_export_metadata no bucket do Cloud Storage.
Use a flag [--async][flag-assíncrono] para evitar que gcloud aguarde a
conclusão da operação. Se você omitir a flag --async, digite
Ctrl+c para não aguardar uma operação. Isso não cancelará a operação.
Defina a flag --database como o nome do banco de dados para importar os tipos ou namespaces específicos. Para o banco de dados padrão, use --database='(default)'.
rest
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: ID do projeto
- bucket-name: nome do bucket do Cloud Storage
- object-name: 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 a esta:
{
"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"
}
}
Exportar e importar dados da PITR
É possível exportar seu banco de dados para o Cloud Storage de dados PITR consistentes
usando o comando gcloud firestore export. É possível exportar dados PITR em que o carimbo de data/hora é um minuto inteiro nos
últimos sete dias, mas não anterior ao earliestVersionTime. Se os dados não existirem mais no carimbo de data/hora especificado, a operação de exportação falhará.
A operação de exportação da PITR é compatível com todos os filtros, incluindo a exportação de todas as entidades e a exportação de tipos ou namespaces específicos.
Exporte o banco de dados, especificando o parâmetro
snapshot-timepara o carimbo de data/hora de recuperação necessário.gcloud
Execute o comando a seguir para exportar o banco de dados para o bucket.
gcloud firestore export gs://[BUCKET_NAME_PATH] \ --snapshot-time=[PITR_TIMESTAMP] \ --collection-ids=[COLLECTION_IDS] \ --namespace-ids=[NAMESPACE_IDS]Em que,
PITR_TIMESTAMP: um carimbo de data/hora da PITR na granularidade de minutos, por exemplo,2023-05-26T10:20:00.00Z.
Também é possível [exportar um subconjunto específico de tipos e/ou namespaces com um filtro de entidade][export-kind].
Observe os seguintes pontos antes de exportar dados PITR:
- Especifique o carimbo de data/hora no formato
RFC 3339.
Por exemplo,
2020-09-01T23:59:30.234233Z. - Verifique se o carimbo de data/hora especificado é de um minuto inteiro nos últimos sete dias, mas não antes do
earliestVersionTime. Se os dados não existirem mais no carimbo de data/hora especificado, você receberá um erro. - Não haverá cobrança pela falha na exportação da PITR.
Importar para um banco de dados.
Use as etapas em Importar todas as entidades para importar seu banco de dados exportado. Se alguma entidade já existir no seu banco de dados, ela será substituída. Também é possível [importar um subconjunto específico de tipos e/ou namespaces com um filtro de entidade][import-kind].
Importar transformações
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 código do projeto de destino. Se essa atualização aumentar seus tamanhos de entidade, é possível que se causem erros de "entidade muito grande" ou "entradas de índice muito grandes" para operações de importação.
Para evitar erros, importe para um projeto de destino com um ID de projeto mais curto. 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 operações de longa duração. Essas chamadas de método podem levar um tempo significativo para serem concluídas.
Depois de iniciar uma operação de exportação ou importação, o modo Datastore atribui à operação um nome exclusivo. 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 em andamento 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 conferir uma lista das operações de execução longa na página Importar/Exportar do console do Google Cloud.
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
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"
}
}
]
}
rest
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: 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 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 consultar uma lista das operações de exportação e importação mais recentes na página Importação/Exportação do console do Google Cloud.
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em 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
rest
Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:
- project-id: 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 a esta:
{
"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:
workEstimatedmostra o número total estimado de bytes e documentos que uma operação processará. O modo Datastore pode omitir essa métrica se não puder fazer uma estimativa.workCompletedmostra 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 deworkEstimated.
Divida workCompleted por workEstimated para ter uma estimativa aproximada do andamento. A estimativa pode ser imprecisa, porque ela depende da coleção de estatísticas em atraso.
Por exemplo, veja o status do andamento 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 for concluída, a descrição da operação conterá "done":
true. Veja o valor do campo state para
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 Importar/Exportar no console do Google Cloud Platform.
No Console do Google Cloud, acesse a página Bancos de Dados.
Selecione o banco de dados necessário na lista de bancos de dados.
No menu de navegação, clique em 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 documentos já exportados no Cloud Storage, e uma operação de importação cancelada deixa implantadas atualizações já feitas em 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
É necessário ativar o faturamento para o projeto do Google Cloud antes de você usar o serviço de exportação e importação gerenciadas. As operações de exportação e importação influenciam seus custos do Google Cloud das seguintes maneiras:
- Leituras e gravações de entidades realizadas por operações de exportação e importação são contabilizadas nos custos do Firestore em modo Datastore. As operações de exportação geram uma operação de leitura por entidade exportada. As operações de importação geram uma operação de gravação por entidade importada.
- Os arquivos de saída armazenados no Cloud Storage contam para os custos de armazenamento de dados do Cloud Storage.
As operações de exportação ou importação não vão acionam os alertas de orçamento do Google Cloud até a conclusão. 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.
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 Faturamento do Cloud, é possível usar esse rótulo para visualizar os custos relacionados às operações de importação e exportação:
Diferenças entre os 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 Datastore Admin Console. As exportações e importações gerenciadas são um novo serviço que não compartilha dados com o recurso de backup e restauração do App Engine, que é administrado pelo console do Google Cloud.
O serviço de exportação e importação gerenciadas não aceita os mesmos metadados que o backup de administração do Datastore e não armazena o status de andamento 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 gerenciada é compatível com versões anteriores dos arquivos de backup do Datastore Admin. É possível importar um arquivo de backup 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 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.
Limite de colunas do BigQuery
O BigQuery impõe um limite de 10 mil colunas por tabela. As operações de exportação geram um esquema de tabela do BigQuery para cada tipo. Nesse esquema, cada propriedade exclusiva dentro das entidades de um tipo se torna uma coluna de esquema.
Se um esquema de BigQuery de um tipo ultrapassar 10 mil colunas, a operação de exportação tentará permanecer abaixo do limite de coluna tratando entidades incorporadas como blobs. Se essa conversão elevar o número de colunas no esquema para 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 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
O Firestore usa um agente de 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 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
Anteriormente, o Firestore usava a conta de serviço padrão do App Engine em vez do agente de serviço do Firestore. Se o banco de dados ainda usar a conta de serviço do App Engine para importar ou exportar dados, recomendamos que você siga as instruções desta seção para migrar para o uso do agente de serviço do Firestore.
- Conta de serviço do App Engine
PROJECT_ID@appspot.gserviceaccount.com
O agente de serviço do Firestore é preferível porque é específico para o Firestore. A conta de serviço do App Engine é compartilhada por mais de um serviço.
Visualizar conta de autorização
Você pode verificar qual conta suas operações de importação e exportação usam para autorizar solicitações na página Importar/Exportar no console do Google Cloud Platform. Também é possível conferir se o banco de dados já usa o agente de serviço do Firestore.
-
No Console do Google Cloud, acesse a página Bancos de Dados.
- Selecione o banco de dados necessário na lista de bancos de dados.
-
No menu de navegação, clique em Importar/Exportar.
- Veja a conta de autorização ao lado do rótulo Importar/exportar jobs executados como.
Se o projeto não usa o agente de serviço do Firestore, é possível migrar para o agente com uma destas técnicas:
- Migrar um projeto verificando e atualizando as permissões do bucket do Cloud Storage (recomendado).
- Adicionar uma restrição de política em toda a organização que afete todos os projetos dela.
A primeira dessas técnicas é recomendada porque localiza o escopo do efeito em um único projeto do modo Datastore. A segunda técnica não é preferível porque não migra permissões existentes de bucket do Cloud Storage. Porém, ela oferece compliance de segurança no nível da organização.
Migrar verificando e atualizando as permissões do bucket do Cloud Storage
O processo de migração tem duas etapas:
- Atualizar permissões do bucket do Cloud Storage. Consulte a próxima seção para mais detalhes.
- 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, é necessário conceder permissões do agente de serviço do Cloud Firestore para esse bucket. Por exemplo, as 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 mudanças nas permissões. O agente de serviço do Firestore pode acessar buckets no mesmo projeto por padrão.
Atualize as permissões dos buckets do Cloud Storage de outros projetos para fornecer
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 a um
bucket do Cloud Storage. Se você precisar conceder apenas permissões de leitura ou
gravação, use uma
função personalizada.
O processo de migração descrito na seção a seguir ajuda a identificar os buckets do Cloud Storage que talvez exijam atualizações das permissões.
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. Uma vez concluída, a migração não pode ser desfeita.
-
No Console do Google Cloud, acesse a página Bancos de Dados.
- Selecione o banco de dados necessário na lista de bancos de dados.
-
No menu de navegação, clique em Importar/Exportar.
-
Se o projeto ainda não tiver sido migrado para o agente de serviço do Firestore, você vai encontrar um banner descrevendo a migração e um botão Verificar status do bucket. A próxima etapa ajuda você 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 a lista terminar de ser carregada.
Essa lista inclui buckets usados recentemente em operações de importação e exportação, mas que atualmente não concedem permissões de leitura e gravação ao agente de serviço do modo Datastore.
- Anote o nome principal do agente de serviço do modo Datastore do seu projeto. O nome do agente de serviço aparece abaixo do identificador Agente de serviço que receberá acesso.
-
Para qualquer bucket na lista que você usar em operações futuras de importação ou exportação, siga estas etapas:
-
Na linha da tabela desse bucket, clique em Corrigir. A página de permissões do bucket será aberta em uma nova guia.
- Clique em Adicionar.
- No campo Novos principais, insira o nome do agente de serviço do Firestore.
- No campo Selecionar um papel, selecione Agentes de serviço > Agente de serviço do Firestore.
- Clique em Salvar.
- Volte para a guia na página de importação/exportação do modo Datastore.
- Repita essas etapas para outros buckets na lista. Analise todas as páginas da lista.
-
-
Clique em Migrar para o agente de serviço do Firestore. Se ainda houver buckets com falha nas verificações de permissão, será necessário confirmar a migração clicando em Migrar.
Um alerta informa quando a migração é concluída. A migração não pode ser desfeita.
Ver o status da migração
Para verificar o status da migração do projeto:
-
No Console do Google Cloud, acesse a página Bancos de Dados.
- Selecione o banco de dados necessário na lista de bancos de dados.
-
No menu de navegação, clique em Importar/Exportar.
-
Procure a principal ao lado do rótulo Importar/exportar jobs executados como.
Se a principal for
service-PROJECT_NUMBER@gcp-sa-firestore.iam.gserviceaccount.com, seu projeto já migrou para o agente de serviço do Firestore. Não é possível desfazer a migração.Se o projeto não tiver sido migrado, um banner aparecerá na parte superior da página com um 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 em toda a organização
-
Defina a restrição a seguir na política da organização:
Exigir o agente de serviço do Firestore para importação/exportação (
firestore.requireP4SAforImportExport).Essa restrição exige que as operações de importação e exportação usem o agente de serviço do Firestore para 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 adequadas do Cloud Storage para o agente de serviço do Firestore.
Se a restrição criar erros de permissão para os fluxos 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 do bucket do Cloud Storage, é possível ativar a restrição novamente.