Práticas recomendadas e tutoriais

Lidar com anexos e blobs de dados binários com o Couchbase Mobile

Couchbase Mobile suporta um modelo de dados NoSQL no estilo de documento JSON. Além de suportar os tipos de dados JSON padrão, o Couchbase Mobile também suporta dados binários que incluem imagens, áudio, vídeo, arquivos PDF, etc. Um documento JSON pode ser associado a um ou mais elementos de dados binários chamados de "anexos" ou "blobs". Os dados binários podem ser sincronizados entre os clientes do Couchbase Lite e o servidor por meio do Sync Gateway. Nesta postagem, discutiremos como criar anexos de dados binários e como recuperá-los e atualizá-los. Também damos uma olhada nos bastidores sobre como os anexos são representados internamente, as idiossincrasias relacionadas e como lidar com elas.

Tudo neste post se aplica a uma implantação baseada no Couchbase Mobile 2.x.

Histórico: Anexos e blobs

O suporte à associação de dados binários com documentos JSON no Couchbase Mobile evoluiu ao longo dos anos. A representação interna dos dados binários no documento JSON mudou nas versões do Couchbase Mobile. No Couchbase Mobile 1.x, os dados binários eram armazenados na forma de "anexos" em um documento de nível superior "_anexos". O Couchbase Mobile introduziu o atributo bolha para armazenar dados binários. Na maioria dos casos, a discrepância entre as representações nas versões é perfeitamente tratada pelo Couchbase Mobile, de modo que os usuários finais não precisam fazer nada de especial em seus aplicativos para lidar com isso. No entanto, há certos casos em que os desenvolvedores de aplicativos precisam tomar medidas adicionais para lidar com a discrepância. Também discutiremos essas medidas nesta postagem e tentaremos responder a algumas perguntas frequentes.

Fluxo de trabalho #1: manipulação de anexos criados no Couchbase Lite

Vamos dar uma olhada em como você pode criar documentos JSON com anexos de dados binários com o Couchbase Lite e sincronizá-los com o lado do servidor. Este é o fluxo que estaremos descrevendo:

Criar anexos de dados binários no Couchbase Lite

Os desenvolvedores devem usar o API de blob para criar dados de blob. Um documento pode ser associado a um ou mais anexos ou blobs. Aqui está um trecho de código que mostra o uso dessa API no Swift. Consulte a documentação do desenvolvedor para obter trechos de código equivalentes para outras plataformas.

Representação interna

Quando o documento é criado no Couchbase Lite, internamente, ele tem a seguinte aparência:

Observe o "@type": "blob" criado para os dados do tipo de imagem.

Observação que existem vários metadados em nível de sistema, como _id que estão incluídos no documento. Por questões de brevidade, nem tudo é mostrado no exemplo. Os aplicativos nunca devem fazer suposições sobre o formato e a disponibilidade dos metadados em nível de sistema e, por esse motivo, nunca devem acessar esses atributos diretamente. Sempre use as opções de recuperação de metadados, como meta().id.

Sincronização de anexos com o Sync Gateway

O Sync Gateway é compatível com versões anteriores do Couchbase Mobile 1.x. Isso significa que o Sync Gateway precisa ser capaz de processar dados binários usando a versão 1.x _. anexos bem como a representação de estilo 2.x bolha tipo. Isso também implica que, quando o cliente Couchbase Lite 2.x envia dados para o Sync Gateway, ele precisa enviá-los em um formato compatível com os clientes 1.x.

Por esse motivo, quando o Couchbase Lite sincroniza o documento com o Sync Gateway, ele adiciona a tag _anexos entrada no documento. Portanto, o documento, quando enviado para cima, seria parecido com o exemplo abaixo. A lista de anexos associados ao documento é especificada no campo _anexos objeto.

Observação que existem vários metadados em nível de sistema, como _id que está incluído no documento. Por questões de brevidade, nem tudo é mostrado no exemplo. Os aplicativos nunca devem fazer suposições sobre o formato e a disponibilidade dos metadados em nível de sistema e, por esse motivo, nunca devem acessar esses atributos diretamente. Sempre use as opções de recuperação de metadados, como meta().id.

Recuperação de anexo no Sync Gateway

Os dados do anexo devem ser recuperados por meio do Sync Gateway _anexos REST endpoint. No momento da redação deste post, os anexos não podem ser gerenciados diretamente usando os SDKs do Couchbase Server.

Aqui está um exemplo de comando curl para recuperar o(s) anexo(s) associado(s) a um documento usando o comando _anexos REST. Substitua o cabeçalho de autorização por credenciais adequadas correspondentes ao usuário configurado em seu sistema. Além disso, observe o nome do anexo, "bolha_image" é a versão codificada do URL de "blob/image"_.

Atualização de anexos no Sync Gateway

Os dados do anexo devem ser atualizados por meio do Sync Gateway _anexos REST endpoint. No momento da redação deste post, os anexos móveis não podem ser gerenciados usando os SDKs do Couchbase Server.

Aqui está um exemplo de comando curl para atualizar um anexo associado a um documento usando o _anexos REST. Você substituiria o cabeçalho de autorização por credenciais adequadas correspondentes ao usuário configurado em sua instalação. Além disso, observe que o cabeçalho "rev" deve ser fornecido. Esse parâmetro corresponde à revisão do documento que deve ser atualizado. Você pode recuperar o revId usando o parâmetro GET documento REST.

Mas... espere... uma incompatibilidade!

Agora, depois de atualizar o anexo, se você recuperar o documento usando o GET documento REST,

A resposta correspondente seria algo parecido com isto:

Você perceberá que o _Anexo e bolha não coincidem. Enquanto o _Anexo aponta para a imagem mais recente, a entrada bolha ainda descreve a imagem antiga. Mas tudo bem!

O motivo dessa discrepância é o fato de o Sync Gateway lidar apenas com anexos do estilo 1.x.

Então, como isso ainda funciona?

Isso funciona porque, no contexto do Sync Gateway que lida com anexos no estilo 1.x, somente a entrada do anexo é honrada.

Mas e quanto ao Couchbase Lite? O que acontece quando o documento atualizado é sincronizado pelo cliente Couchbase Lite 2.x?

Quando o documento é replicado pelo cliente do Couchbase Lite 2.x, o Couchbase Lite procura a presença de _anexos e bolhas dentro do documento e implementa a lógica apropriada para identificar que se trata de um documento de estilo 2.x criado por um cliente 2.x, mas que foi posteriormente atualizado por um cliente 1.x (como a API REST do Sync Gateway). Portanto, ele trata o _anexos como o anexo "real" e unifica a entrada de bolha correspondente.

Do ponto de vista do desenvolvedor, tudo isso é tratado automaticamente. Portanto, você não precisa se preocupar com nenhum dos detalhes. Como desenvolvedor, você teria que saber como recuperar o anexo atualizado de dentro do aplicativo habilitado para o Couchbase Lite.

Recuperação de anexos atualizados no Couchbase Lite

Quando o anexo atualizado for sincronizado com seu aplicativo Couchbase Lite, use o comando API de blob para recuperar os dados. Aqui está um trecho de código que mostra o uso dessa API em swift. Consulte a documentação do desenvolvedor para obter trechos de código equivalentes para outras plataformas.

Agora vamos dar uma olhada no fluxo inverso.

Fluxo de trabalho #2: manipulação de anexos criados no Sync Gateway

Vamos dar uma olhada em como você pode criar documentos JSON com anexos de dados binários no Sync Gateway e sincronizá-los com o lado do Couchbase Lite.
Esse é o fluxo que estaremos descrevendo.

Criar anexos de dados binários no servidor

Para anexar dados binários no lado do Couchbase Server que podem ser sincronizados com os clientes por meio do Sync Gateway, você teria que usar o Sync Gateway ponto de extremidade REST dos anexos. No momento da redação deste post, os anexos compatíveis com dispositivos móveis não podem ser criados diretamente usando os SDKs do Couchbase Server. Os dados do anexo criados por meio do endpoint REST do Sync Gateway são mantidos no bucket do Couchbase Server e sincronizados com os clientes do Couchbase Lite, sujeitos às políticas de controle de acesso configuradas no Sync Gateway.

Para fazer isso, primeiro crie um documento (ou recupere um documento criado anteriormente) e, em seguida, crie o anexo para o documento. Como alternativa, você poderia criar um documento de várias partes com dados JSON e binários. Mas isso pode ser tedioso, pois você também precisaria gerar os metadados relevantes do anexo. Portanto, as etapas descritas abaixo são a minha opção preferida

  • Criar documento

Um documento JSON pode ser criado diretamente no Couchbase Server usando o SDK do Couchbase Server ou a interface do usuário do administrador, ou você pode criá-lo usando o Documento PUT API REST. O documento também poderia ter sido sincronizado a partir de um cliente Couchbase Lite.

Aqui está um exemplo de uso do endpoint REST do Sync Gateway para criar um documento com Id "user::jane". Substitua o cabeçalho de autorização por credenciais adequadas correspondentes ao usuário configurado em sua instalação.

A resposta seria semelhante à seguinte:

  • Criar anexo para documento no Sync Gateway

Os dados do anexo devem ser criados por meio do Sync Gateway _anexos REST endpoint. Essa etapa é idêntica ao fluxo anterior quando um anexo estava sendo atualizado por meio do ponto de extremidade REST.

Aqui está um exemplo de comando curl para atualizar um anexo associado a um documento usando o _anexos REST. Você substituiria o cabeçalho de autorização por credenciais adequadas correspondentes ao usuário configurado em sua instalação. O cabeçalho "rev" deve ser fornecido. Esse parâmetro corresponde à revisão do documento que deve ser atualizado.

Representação interna

Quando o documento for atualizado pelo Sync Gateway, ele terá a seguinte aparência
Se você recuperar o documento usando o GET documento REST,

A resposta correspondente seria algo parecido com isto:

A criação de anexos usando a API REST de anexos do Sync Gateway resultará na representação de anexos no estilo 1.x. Observe que não há metadados "blob" no estilo 2.x. É importante observar isso quando você acessar o documento no Couchbase Lite

Recuperação de anexos atualizados no Couchbase Lite

Quando o documento criado anteriormente é sincronizado com o lado do Couchbase Lite, ele detecta que se trata de um documento de estilo 1.x e deixa o _anexos intacta. Ele trata os objetos aninhados dentro do _anexos como bolhas. No entanto, o documento não é atualizado automaticamente para incluir a entrada "blob" que é adicionada. Portanto, seu aplicativo precisaria procurar a presença de bolhas usando a função API de blob em ambos os locais.

PERGUNTAS FREQUENTES

Para concluir, compilei uma lista de perguntas frequentes relacionadas ao manuseio de anexos no Couchbase Mobile

Onde os anexos são armazenados?

No Couchbase Lite, os anexos são armazenados na instância do banco de dados do Couchbase Lite que contém o documento correspondente. Ele é armazenado separadamente do documento que contém os metadados associados que contêm a referência ao anexo. Se o mesmo anexo for compartilhado por vários documentos, apenas uma única instância do anexo será armazenada no banco de dados.

No Couchbase Server, os anexos são armazenados no mesmo bucket do Couchbase Server que o documento correspondente. Ele é armazenado separadamente do documento que contém os metadados associados que contêm a referência ao anexo. Se o mesmo anexo for compartilhado por vários documentos, somente uma única instância do anexo será armazenada no bucket.

Há um limite para o número de anexos que podem ser associados a um documento?

Você pode anexar um ou mais anexos a um documento JSON. Não há limites rígidos para o número de anexos que podem ser associados a um documento. No entanto, como os metadados do anexo são armazenados nos xattrs do documento (quando shared_bucket_access está ativado), o número de anexos é limitado pelo tamanho permitido dos metadados de sincronização por documento. Com metadados de anexos variando de 100 a 200 bytes e limite de tamanho de metadados de sincronização de 1 MB por documento, há limites práticos para o número de anexos que podem ser associados a um documento.

Qual é o tamanho máximo de um anexo?

O tamanho máximo de cada anexo é de 20 MB. Isso decorre dos limites de tamanho dos documentos no Couchbase Server. Embora o próprio Couchbase Lite permita anexos de tamanho superior a 20 MB, isso é aceitável, desde que o anexo seja apenas local e seja garantido que nunca será sincronizado com o servidor. No entanto, os desenvolvedores são alertados para não criarem anexos tão grandes, pois eles serão rejeitados pelo Sync Gateway.

Os anexos são sincronizados toda vez que o documento JSON associado é alterado?

O protocolo de replicação é otimizado para sincronizar anexos somente quando houver atualizações para eles. Isso significa que eles não são enviados ou retirados pelos clientes do Couchbase Lite, mesmo que haja atualizações em outros dados nos documentos JSON associados.

Como o protocolo lida com falhas ao sincronizar anexos?

O protocolo é muito robusto em termos de tratamento de falhas de sincronização, por exemplo, devido a interrupções na rede. Os documentos não são mantidos pelo Sync Gateway ou no Couchbase Lite até que todos os anexos ou blobs associados sejam sincronizados com êxito. Portanto, pode haver um intervalo de tempo em que você pode acabar com anexos/blogs órfãos que não têm documentos associados. Isso não é um problema, pois a sincronização subsequente do documento reconhecerá que o anexo já está persistente e não tentará ressincronizá-lo novamente.

O que vem a seguir

O Couchbase Mobile oferece uma interface fácil de usar para gerenciar anexos. Dê uma olhada no documentação para obter detalhes sobre o manuseio de blob em cada uma das plataformas.
Se tiver dúvidas ou comentários, deixe um comentário abaixo ou entre em contato comigo pelo Twitter ou enviar-me um e-mail. O Fóruns de desenvolvimento do Couchbase são um ótimo lugar para se envolver com a comunidade de desenvolvimento do Couchbase.

 

Compartilhe este artigo
Receba atualizações do blog do Couchbase em sua caixa de entrada
Esse campo é obrigatório.

Autor

Postado por Priya Rajagopal, Diretora Sênior, Gerenciamento de Produtos

Priya Rajagopal é diretora sênior de gerenciamento de produtos da Couchbase, responsável pelas plataformas de desenvolvedor para a nuvem e a borda. Ela desenvolve software profissionalmente há mais de 20 anos em vários cargos técnicos e de liderança de produtos, com mais de 10 anos de foco em tecnologias móveis. Como delegada de padrões de IPTV da TISPAN, ela foi uma das principais colaboradoras das especificações de padrões de IPTV. Ela tem 22 patentes nas áreas de rede e segurança de plataforma.

8 Comentários

  1. Oi Priya,
    Aqui está outra pergunta para a seção de perguntas frequentes, se possível.

    Como os BLOBs ou anexos são binários e não podem ser processados, pesquisados, compactados, comparados, etc., eles são armazenados em um enorme banco de dados em vez de em uma pasta com um nome de arquivo exclusivo. Por que eles são armazenados em um enorme banco de dados em vez de em uma pasta com nome de arquivo exclusivo?

    É possível ter uma pasta contendo um site que gerencia seu banco de dados-documentos-conteúdos sendo replicado para os vários nós?

  2. Hi
    Depende do caso de uso. Se estiver falando de grandes volumes de dados binários, armazená-los em um CDN/armazenamento externo é a opção preferida. Nesse caso, você armazenará dados binários externos ao servidor Couchbase e incluirá o URL de referência no documento. O aplicativo será responsável por baixar e enviar os anexos e atualizar as referências correspondentes ao documento quando essas alterações forem detectadas

    A vantagem de tratar os anexos binários como "Documentos" é que você está obtendo (eventuais) garantias de consistência porque o push and pull é tratado pelo nosso protocolo de sincronização. Nós nos encarregamos de detectar alterações nos anexos e extrair as alterações quando necessário.

    Mesmo que você opte por armazenar os anexos no repositório externo para evitar o armazenamento no bucket do servidor, se estiver buscando o recurso offline-first, ainda será necessário persistir localmente os anexos no Couchbase lite para que eles estejam disponíveis mesmo quando o cliente estiver offline

    Além disso, os dados binários são bem compactados.

  3. Oi Priya,

    Não consigo entender por que os SDKs do Couchbase Server não oferecem uma opção para adicionar anexos (blobs) diretamente e precisamos passar pelo gateway de sincronização. Você poderia explicar melhor isso? Há algum plano de adicionar esse recurso nas versões futuras?

    Melhor,
    PShri

  4. Hi
    O suporte ao uso do SDK do CBS para a criação de dados binários que podem ser sincronizados com clientes couchbase lite está em nosso radar. Enquanto isso, o padrão típico é criar o documento por meio do SDK e usar o endpoint REST do Sync Gateway para associar anexos/dados binários.

  5. Como posso saber quando isso será adicionado ao SDK da CBS? Há algum lugar onde eu possa me inscrever e ficar sabendo sobre isso? Obrigado por responder.

    1. Não sei se entendi a pergunta. O mesmo cliente SDK que está gravando o documento no bucket do servidor será responsável por usar o ponto de extremidade REST para associar/criar o anexo. Portanto, em vez de uma única chamada para criar o documento e o anexo, o cliente do SDK fará duas chamadas: uma chamada INSERT/UPSERT para criar o documento no bucket, seguida pela API REST _attachment para criar o anexo associado ao documento

  6. Oi Priya,

    Você propõe outra maneira de oferecer suporte a anexos enormes (tamanho > 20 MB)?
    É possível dividir o anexo com menos de 20 MB?

    Agradecimentos

    1. Se você tiver anexos tão grandes, recomendamos que os armazene em uma CDN externa e coloque o URL no documento. Provavelmente, você não deseja armazenar dados binários tão grandes em um banco de dados. Seu aplicativo seria responsável por gerenciar os anexos. Não há nenhum mecanismo integrado para dividir e mesclar os anexos.

Deixe um comentário

Pronto para começar a usar o Couchbase Capella?

Iniciar a construção

Confira nosso portal do desenvolvedor para explorar o NoSQL, procurar recursos e começar a usar os tutoriais.

Use o Capella gratuitamente

Comece a trabalhar com o Couchbase em apenas alguns cliques. O Capella DBaaS é a maneira mais fácil e rápida de começar.

Entre em contato

Deseja saber mais sobre as ofertas do Couchbase? Deixe-nos ajudar.