Configurações do Sync
Nesta página
- Configurações disponíveis
- Cluster to Sync
- Tipo de sincronização
- Modo de desenvolvimento
- Nome do Banco de Dados (somente Modo de Desenvolvimento)
- Campos de query
- Permissões
- Ingestão de dados
- Tempo máximo offline do cliente
- Recuperação do cliente
- Referência do arquivo de configuração de sincronização
- Sincronizar objeto de configuração
Esta página explica as configurações disponíveis ao habilitar ou configurar o Device Sync.
Configurações disponíveis
Cluster to Sync
O nome da fonte de dados vinculada do Atlas cluster onde você deseja armazenar seus dados sincronizados.
Você não pode modificar este campo enquanto o Device Sync estiver habilitado. Você deve encerrar a sincronização antes de selecionar um cluster diferente.
Observação
Requisitos de fonte de dados para Device Sync
Para habilitar o Device Sync, seu aplicativo do App Services App deve ter pelo menos uma fonte de dados vinculada que atenda aos seguintes requisitos:
Um cluster de MongoDB Atlas não fragmentado executando o MongoDB 5.0 ou posterior.
O cluster não pode ser uma instância sem servidor ou instância do banco de dados de dados federado. Consulte Limitações da fonte de dados.
Tipo de sincronização
Importante
O tipo de sincronização só está disponível para aplicativos de sincronização baseada em partição
A capacidade de selecionar o Tipo de Sincronização da sua aplicação só está disponível para organizações com pelo menos uma aplicação de sincronização baseada em partição existente em seu projeto.
A sincronização baseada em partição foi descontinuada e não é permitida para novas configurações do Sync. Em vez disso, todas as novas configurações de sincronização são padronizadas automaticamente para o modo Flexible Sync recomendado.
Ao ativar o Device Sync, você pode selecionar um dos seguintes modos de sincronização:
O Flexible Sync permite definir uma query no cliente e sincronizar apenas os objetos que correspondem à query. Com assinaturas do lado do cliente do cliente , os aplicativos do cliente podem:
Manter queries
Reagir às alterações
Adicionar, alterar ou excluir queries
O Flexible Sync é o único modo disponível para novas configurações do Sync.
A sincronização baseada em partição é um modo de sincronização mais antigo que foi descontinuado e não é permitido para novas configurações de sincronização.
Se você tiver um aplicativo existente que já usa a antiga sincronização baseada em partição, recomendamos que você migre para a Flexible Sync. A migração é um processo automático que não requer nenhuma alteração no código do aplicativo cliente , exceto a atualização das versões do SDK. Para obter mais informações, consulte Migrar modos de Device Sync .
Não é possível alterar o tipo de sincronização enquanto o Device Sync estiver ativado. Você deve encerrar ou pausar a sincronização antes de fazer suas alterações.
Modo de desenvolvimento
O modo de desenvolvimento é uma configuração que permite ao Device Sync inferir e atualizar esquemas com base em modelos de dados do lado do cliente. É uma forma de otimizar o desenvolvimento, mas não deve ser usado para a produção.
O Modo de Desenvolvimento acelera o desenvolvimento ao permitir que você crie esquemas diretamente no código do aplicativo cliente.
Quando você sincroniza um domínio, o Atlas App Services mapeia cada tipo de objeto sincronizado para sua própria coleção no banco de dados especificado por Nome do banco de dados (somente no modo de desenvolvimento). Se você atualizar o modelo de objeto no lado do cliente, o App Services atualizará o esquema da coleção para corresponder. Isso permite que você atualize objetos no código do cliente à medida que desenvolve o aplicativo.
Você pode usar regras de acesso a dados junto com o modo de desenvolvimento. Observe que alterações de esquemas ignoram as regras de acesso a dados. Isso significa que qualquer cliente pode atualizar o esquema de backend alterando o modelo do cliente.
Para saber mais sobre como os esquemas de objetos de Realm são mapeados para os esquemas do App Services ao usar o modo de desenvolvimento, consulte Mapeamento de modelos de dados.
Para mais informações sobre como modificar esquemas de objetos sincronizados, consulte Atualizar seu modelo de dados.
Importante
Desabilitar o modo de desenvolvimento para aplicativos de produção
O modo de desenvolvimento é um utilitário de desenvolvimento que não é adequado para uso de produção. Certifique-se de desligar o Modo de desenvolvimento antes de tornar seu app acessível em um ambiente de produção.
Mudanças de última hora
Aplicativos do App Services no modo de desenvolvimento criados depois de 13 de setembro de 2023 podem fazer alterações significativas em esquemas de objetos sincronizados usando o código do cliente.
Se o seu aplicativo foi criado antes de 13 de setembro de 2023, entre em contato com o suporte para habilitar essa funcionalidade.
Pré-requisitos
Aplicativo do App Services criado após 13 de setembro de 2023
MongoDB 5.0 ou posterior com compatibilidade com o Flexible Sync
Versão mínima do SDK:
Realm C++ SDK v1.0.0
Realm Flutter SDK v1.6.0
Realm Java SDK v10.16.2
Realm Kotlin SDK v11.1.1
Realm .NET SDK v11.6.0
Realm Node.js SDK v12.2.0
Realm React Native SDK v12.2.0
Realm Swift SDK v10.42.2
Observação
Aplicativos criados antes de 13 de setembro de 2023
Para aplicações criadas antes de 13 de setembro de 2023, você precisa atualizar o esquema de objetos na UI do App Services. Para detalhes, consulte Atualizar modelo de dados
Para fazer uma alteração significativa no código do cliente:
Exclua seu domínio local e dados. Isso não afetará dados sincronizados com o backend. Alterações locais que não foram sincronizadas serão removidas e não poderão ser recuperadas.
Altere seu modelo de objeto local.
Abra um realm com seu modelo de objeto atualizado.
Execute seu aplicativo cliente para sincronizar suas alterações no back-end.
Para excluir um arquivo de Realm, use os métodos específicos do Realm SDK:
Efeitos colaterais ao habilitar o modo de desenvolvimento
Habilitar o modo de desenvolvimento gera dois efeitos colaterais:
Ativando autenticação anônima.
Desabilitar esquemas de distribuição.
Se seu aplicativo não precisar de autenticação anônima, recomendamos desabilitá-la depois de habilitar o modo de desenvolvimento.
Não é possível reabilitar esquemas de distribuição na UI até desabilitar o modo de desenvolvimento. No entanto, você ainda pode criar esquemas de distribuição manualmente por meio da CLI ou da API de administrador.
Nome do Banco de Dados (somente Modo de Desenvolvimento)
Ao ativar o Modo de desenvolvimento, você especifica um banco de dados para armazenar objetos sincronizados. O App Services cria novas coleções nesse banco de dados do Modo de desenvolvimento para cada tipo de objeto sincronizado.
Exemplo
Especifique um banco de dados do modo de desenvolvimento de myapp. Seu cliente iOS tem um modelo Person. Você sincroniza um realm que contém uma instância do objeto Person. O modo de desenvolvimento cria um esquema no servidor associado ao modelo. O objeto sincroniza com a collection myapp.Person.
Os App Services continuam a criar novos esquemas e coleções do lado do servidor para cada novo tipo de objeto. Se, posteriormente, você adicionar um objeto Dog , esse objeto será sincronizado com uma nova coleção de myapp.Dog que o App Services criará.
Campos de query
Ao configurar o Flexible Sync, você especifica os nomes de campo que seu aplicativo cliente pode executar uma query em uma assinatura do Flexible Sync. Os rendimentos que podem ser utilizados em uma query de assinatura são chamados de campos de query.
Exemplo
Em um aplicativo de lista de tarefas, você pode definir assignee ou owner como campos de query. No lado do cliente, você pode executar queries das tarefas cujo assignee ou owner corresponda ao usuário conectado.
Escopos de campos de query
Campos de query são aplicados a um escopo que você determina ao configurá-los. Os dois escopos disponíveis são:
Campos de query globais: com escopo em todas as collections no esquema de um aplicativo.
Campos de query da coleção: com escopo definido para uma única coleção no aplicativo.
O escopo de um campo de query para uma collection específica reduz a quantidade de armazenamento de backup do Atlas necessária para armazenar metadados do Sync.
Você pode usar regras e permissões para configurar um controle de acesso mais granular por collection. Você pode definir regras e permissões em nível de collection para campos de query globais e de collections.
Configurar campos de query
Você pode especificar automaticamente os campos consultáveis ativando o Modo de desenvolvimento. Os campos que aparecem em queries de cliente durante o uso do modo de desenvolvimento são adicionados automaticamente como campos consultáveis de coleção para a coleção para a qual uma query está sendo executada.
Os nomes de campo que você fornece são strings arbitrárias. Se um tipo de objeto tiver um campo cujo nome corresponda ao nome de campo que você forneceu (e atenda a outros critérios de elegibilidade), esse campo ficará disponível para o Device Sync fazer query.
Configurar campos de query indexados
Você só pode adicionar ou remover um campo de query indexado se o Device Sync não estiver habilitado. Se o Device Sync já estiver em execução no seu aplicativo, será necessário encerrar o Sync e configurar o campo de query indexado ao reabilitá-lo.
Isso faz com que o cliente seja redefinido para qualquer cliente que tente se reconectar depois de reativar o Sync.
Tipos de campos elegíveis
Flexible Sync permite apenas campos primitivos de nível superior com um tipo escalar como campos de query. Você também pode incluir arrays desses primitivos como campos de query. Flexible Sync não permite objetos embarcados ou arrays de objetos como campos de query.
Campos de query indexados suportam um subconjunto de tipos de dados. Seu campo de query indexado pode ser um dos seguintes: int64, string, ObjectId, UUID.
Dica
Consulte também: Realm Query Language - Flexible Sync Limitations
Para obter informações sobre as queries que você pode fazer nestes campos, consulte Limitações RQL do Flexible Sync
Nomes de campos reservados
O App Services reserva algumas palavras-chave para o Realm Query Language e outros propósitos. Você não pode usar palavras-chave reservadas como nomes de campo.
O App Services reserva as seguintes palavras-chave com qualquer letra maiúscula:
|
|
|
Exemplo
Você não pode utilizar descending, Descending, DESCENDING ou DeScEnDiNG como um nome de campo.
O App Services também reservam as seguintes palavras-chave com as letras maiúsculas e minúsculas exatas fornecidas:
|
|
|
Exemplo
Você não pode usar true ou TRUE, pois ambas as letras maiúsculas e minúsculas são especificamente reservadas, mas você pode usar True ou tRUE como um nome de campo.
Desempenho e armazenamento
Cada campo de query adiciona um armazenamento de metadados adicional ao seu Atlas cluster e pode levar a um desempenho de gravação enfraquecido. Você deve ter uma quantidade mínima de campos de query necessários para seu aplicativo, e fazer escopo com o mínimo de collections necessárias.
Muitos aplicativos encontram um bom equilíbrio entre o uso do armazenamento e a flexibilidade de query com no máximo 10 campos de query aplicáveis a qualquer coleção. Por exemplo, se você tiver 3 campos de query globais e 7 campos de query de coleção, você terá 10 campos de query que se aplicam à coleção.
Se você tem um campo e deseja fazer query somente em uma collection, mas ele está configurado como um campo de query global, o espaço de armazenamento do Atlas será consumido desnecessariamente. Por exemplo, se você tem um campo user em cada collection, mas o usa somente para fazer queries do Sync em uma única collection, fazer o escopo desse campo como um campo de query de collection reduz os requisitos de armazenamento. Reduzir o escopo significa que o Sync não precisará manter os metadados desse campo para as outras collections nas quais você não está fazendo query no campo user.
Se você precisar reduzir o uso do armazenamento ou melhorar o desempenho, poderá remover campos consultáveis desnecessários do seu aplicativo. No entanto, esteja ciente das consequências de adicionar ou remover campos consultáveis. Para obter mais informações, consulte Consequências da adição ou remoção de campos consultáveis.
Para considerações adicionais, consulte otimizar o desempenho e o armazenamento ao usar a Flexible Sync.
Campos de query indexados
Você pode melhorar o desempenho de determinados tipos de cargas de trabalho adicionando um campo de query indexado. Um campo indexado que pode passar por query é um campo de query global que pode passar por query com mais eficiência, fornecendo melhor desempenho de sincronização. Você pode designar um campo de query global como um campo de query indexado.
Indexar um campo de query melhora o desempenho de queries simples em um único campo, como {“store_id”: 1} ou {“user_id”: “641374b03725038381d2e1fb”}.
O campo consultável indexado deve aparecer nos esquemas de todas as coleções de sincronização e deve usar o mesmo tipo de dados válido. Por exemplo, se o seu campo consultável indexado for store_id, ele deverá aparecer em todas as coleções que você sincronizar e deverá ser do mesmo tipo válido em todas as coleções. Para obter mais informações sobre os tipos de campos que se qualificam, consulte a página Tipos de campos elegíveis.
Você não pode alterar valores de campos de query indexados no cliente
Depois de configurar um campo de query indexado, os dispositivos cliente não poderão atualizar o valor do campo de query indexado de um objeto existente. Por exemplo, se o seu campo de query indexado for store_id, o cliente não poderá alterar este valor de forma direta. Não é possível fazer a alteração a partir do cliente porque pode conflitar com outras atualizações feitas no objeto no mesmo período.
Se você tentar alterar o valor de um campo indexado e de query no dispositivo, isso acionará um erro de gravação compensatório. Para obter mais informações sobre esse erro e o comportamento que ele acarreta, consulte ErrorCompensatingWrite na documentação sobre erros de Flexible Sync.
Você ainda pode alterar este valor diretamente no banco de dados do Atlas.
Aviso
Alterar o valor de campo de query indexado de um objeto através do Atlas pode substituir as atualizações simultâneas do cliente no objeto.
Queries do lado do cliente em campos de query indexados
Se o seu aplicativo usar um campo de query indexado, as queries do lado do cliente em uma inscrição do Flexible Sync devem incluir o campo de query indexado utilizando uma comparação do == ou IN com uma constante pelo menos uma vez. Por exemplo, user_id == 641374b03725038381d2e1fb ou store_id IN {1,2,3}.
Opcionalmente, você pode incluir uma comparação AND, desde que o campo consultável indexado seja comparado diretamente com uma constante usando == ou IN pelo menos uma vez. Por exemplo, store_id IN {1,2,3} AND region=="Northeast" ou store_id == 1 AND (active_promotions < 5 OR num_employees < 10).
As consultas inválidas do Flexible Sync em um campo indexado que pode ser consultado incluem consultas em que:
O campo de consulta indexado não utiliza
ANDcom o resto da consulta. Por exemplostore_id IN {1,2,3} OR region=="Northeast"é inválido porque usaORem vez deAND. Da mesma forma,store_id == 1 AND active_promotions < 5 OR num_employees < 10é inválido porque oANDsó se aplica ao termo ao lado, não à consulta inteira.O campo de consulta indexado não é utilizado em um operador de igualdade. Por exemplo
store_id > 2 AND region=="Northeast"é inválido porque utiliza apenas o operador>com o campo de consulta indexado e não tem uma comparação de igualdade.A query está totalmente ausente do campo de query indexado. Por exemplo,
region=="Northeast"outruepredicatesão inválidos porque não contêm o campo de query indexado.
Consequências da adição ou remoção de campos de query
Você pode atualizar sua configuração do Sync para adicionar ou remover nomes de campos de query enquanto a sincronização estiver habilitada, mas esteja ciente do seguinte:
Quando você adiciona um campo de query, os dispositivos só podem sincronizar nesse campo depois que o dispositivo atingir o ponto no tempo no Device Sync History em que o campo foi adicionado.
Quando você remove um campo de query, qualquer dispositivo que ainda use esse campo terá sua sessão do Device Sync interrompida e deverá fazer um reinício do cliente. Clientes que não utilizam o campo removido não receberão erros. Para não acionar um reinício do cliente ao remover o campo de query, você deve primeiro remover o uso desse campo no lado do cliente.
Se você encerrar a sincronização antes de adicionar ou remover campos que podem passar por query, essas considerações não se aplicam. No entanto, o encerramento da sincronização aciona uma redefinição de cliente para qualquer cliente que tenha sincronizado com seu aplicativo.
Permissões
O Atlas Device Sync impõe regras de acesso a dados baseadas em roles para todas as solicitações para um cluster sincronizado. As regras são expressões JSON dinâmicas que determinam a capacidade do usuário de sincronizar, visualizar e modificar dados.
Para obter detalhes, consulte Permissões baseadas em funções.
Ingestão de dados
Ingestão de dados é uma estratégia de sincronização para aplicativos com volumes de trabalho pesados somente de inserção no lado do cliente. Você pode habilitá-lo para uma ou mais collections. Ele oferece suporte à gravação em qualquer tipo de collection, incluindo uma coleção de série temporal do Atlas.
Por exemplo, um aplicativo IoT que registra dados de sensor com frequência tem uma carga de trabalho de gravação significativa e nenhuma carga de trabalho de leitura. O dispositivo também pode estar offline por longos períodos. A ingestão de dados ignora parte do processamento necessário para a sincronização bidirecional, melhorando significativamente a velocidade de gravação em uma coleção do Atlas.
Outros casos de uso incluem a gravação de dados imutáveis, como faturas de um aplicativo de varejo, ou o registro de eventos de aplicativos, nenhum dos quais exige uma resolução de conflitos.
Você pode aplicar a ingestão de dados a collections individuais. Isso significa que seu aplicativo pode usar a ingestão de dados para escrever alguns dados, mas a Flexible Sync bidirecional em outras collections.
As collections de ingestão de dados servem apenas para a gravação de dados. Você não pode usar queries do Flexible Sync nessas collections. Em vez disso, use Conectar a fontes de dados do MongoDB.
Depois de ativar a Ingestão de dados, você a implementa no aplicativo cliente por meio dos SDKs do cliente. Atualmente, os seguintes SDKs do Realm suportam a Ingestão de dados:
Flutter SDK: transmitir dados para o Atlas - Flutter SDK
Kotlin SDK: Transmitir dados para o Atlas - Kotlin SDK
Node.js SDK: definir um objeto assimétrico
React Native SDK: definir um objeto assimétrico
Swift SDK: Transmitir dados para o Atlas - Swift SDK
O Atlas Device Sync gerencia o ciclo de vida desses dados por completo. Ele é mantido no dispositivo até que a sincronização da ingestão de dados seja concluída e, em seguida, é removido do dispositivo.
Tempo máximo offline do cliente
Tempo máximo offline do cliente determina por quanto tempo o cliente pode ficar offline entre as sessões de sincronização. Alterar esse valor permite equilibrar o acesso offline com o armazenamento usado no Atlas cluster sincronizado. Para obter mais informações, consulte Tempo máximo offline do cliente.
Recuperação do cliente
A Recuperação de Cliente permite que o cliente tente executar automaticamente um reinício do cliente enquanto recupera dados no dispositivo. Para mais informações, consulte Recuperar alterações não sincronizadas.
Referência do arquivo de configuração de sincronização
Você pode encontrar o arquivo de configuração Sincronizar para seu aplicativo no diretório sync de um aplicativo exportado:
app/ └── sync/ └── config.json
Por exemplo, a configuração do Sync abaixo é válida para aplicativos que usam o Flexible Sync.
{ "type": "flexible", "development_mode_enabled": <Boolean>, "service_name": "<Data Source Name>", "database_name": "<Development Mode Database Name>", "state": <"enabled" | "disabled">, "client_max_offline_days": <Number>, "is_recovery_mode_disabled": <Boolean>, "queryable_fields_names": [ <Array of String Field Names> ], "indexed_queryable_fields_names": [ <Array of String Field Names> ], "collection_queryable_fields_names": <Map[String][]String> "permissions": "<Deprecated, Do Not Use>" }
O campo permissions obsoleto ainda pode aparecer na configuração do seu aplicativo exportado. Isso pode indicar que seu aplicativo não foi migrado automaticamente para o sistema de regras unificado ainda. Não exclua este campo até que o seu aplicativo seja migrado.
Sincronizar objeto de configuração
{ "type": "flexible", "development_mode_enabled": <Boolean>, "service_name": "<Data Source Name>", "database_name": "<Development Mode Database Name>", "state": <"enabled" | "disabled">, "client_max_offline_days": <Number>, "is_recovery_mode_disabled": <Boolean>, "queryable_fields_names": ["<Field Name>", ...], "indexed_queryable_fields_names": ["<Field Name>", ...], "collection_queryable_fields_names": { "<Collection Name>": ["<Field Name>", ...], ... } }
Campo | Descrição |
|---|---|
typestring | O modo de sincronização. Há dois modos de sincronização: a Flexible Sync e a antiga sincronização baseada em partição. Recomendamos usar o Flexible Sync. Para obter mais informações sobre sincronização baseada em partição, consulte Sincronização baseada em partição. Opções válidas para uma configuração Flexible Sync:
|
development_mode_enabledboolean | Se true, o modo de desenvolvimento estará habilitado para o aplicativo. Quando habilitado, o App Services armazena automaticamente objetos sincronizados em um banco de dados específico (especificado em database_name) e espelha os tipos de objetos nos esquemas de coleção desse banco de dados. |
service_namestring | O nome da fonte de dados do Atlas cluster a ser sincronizada. Não é possível fazer a sincronização com uma instância sem servidor. |
database_namestring | O nome de um banco de dados no cluster sincronizado em que o App Services armazena dados no modo de desenvolvimento. O App Services gera automaticamente um esquema para cada tipo sincronizado e mapeia cada tipo de objeto para uma coleção no banco de dados. |
statestring | O estado atual do protocolo de sincronização do aplicativo. Opções válidas:
|
client_max_offline_daysnumber | O número de dias que o processo de compactação de back-end aguarda antes de podar agressivamente os metadados que alguns clientes exigem para sincronizar a partir de uma versão antiga de um domínio |
is_recovery_mode_disabledboolean | Se false, o Modo de Recuperação está habilitado para o aplicativo. Enquanto habilitados, os SDKs de Realm que oferecem suporte a esse recurso tentam recuperar alterações não sincronizadas ao executar uma redefinição de cliente. O modo de recuperação está habilitado por padrão. |
queryable_fields_namesstring[] | Uma lista de nomes de campos a serem usados como campos consultáveis globais. |
indexed_queryable_fields_namesstring[] | Uma lista de nomes de campos a serem usados como o campo consultável indexado. Embora essa propriedade seja uma array, o Sync atualmente oferece suporte a apenas um campo consultável indexado. Portanto, essa array pode conter no máximo um elemento. O campo consultável indexado deve estar presente no esquema e ser do mesmo tipo de campo elegível em todas as coleções que você sincronizar. O nome do campo consultável indexado também deve aparecer no |
collection_queryable_fields_names{ [collectionName: string]: string[] } | Um mapa de nomes de coleções e uma lista de campos consultáveis em nível de coleção para cada coleção. |
last_disablednumber | A data e a hora em que a sincronização foi pausada ou desativada pela última vez, representada pelo número de segundos desde a época Unix (1 de janeiro de 1970, 00:00:00 UTC). |
asymmetric_tablesstring[] | Uma array dos nomes de coleções que são definidas como assimétricas com ingestão de dados, onde os clientes podem gravar dados, mas não ler. |