{"id":8755,"date":"2020-06-02T10:01:46","date_gmt":"2020-06-02T17:01:46","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/?p=8755"},"modified":"2023-09-29T13:48:47","modified_gmt":"2023-09-29T20:48:47","slug":"store-sync-binary-data-attachments-blobs-couchbase-mobile","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/pt\/store-sync-binary-data-attachments-blobs-couchbase-mobile\/","title":{"rendered":"Lidar com anexos e blobs de dados bin\u00e1rios com o Couchbase Mobile"},"content":{"rendered":"

Couchbase Mobile<\/a> suporta um modelo de dados NoSQL no estilo de documento JSON. Al\u00e9m de suportar os tipos de dados JSON padr\u00e3o, o Couchbase Mobile tamb\u00e9m suporta dados bin\u00e1rios que incluem imagens, \u00e1udio, v\u00eddeo, arquivos PDF, etc. Um documento JSON pode ser associado a um ou mais elementos de dados bin\u00e1rios chamados de \"anexos\" ou \"blobs\". Os dados bin\u00e1rios 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\u00e1rios e como recuper\u00e1-los e atualiz\u00e1-los. Tamb\u00e9m damos uma olhada nos bastidores sobre como os anexos s\u00e3o representados internamente, as idiossincrasias relacionadas e como lidar com elas.<\/p>\n

Tudo neste post se aplica a uma implanta\u00e7\u00e3o baseada no Couchbase Mobile 2.x.<\/p>\n

Hist\u00f3rico: Anexos e blobs<\/h2>\n

O suporte \u00e0 associa\u00e7\u00e3o de dados bin\u00e1rios com documentos JSON no Couchbase Mobile evoluiu ao longo dos anos. A representa\u00e7\u00e3o interna dos dados bin\u00e1rios no documento JSON mudou nas vers\u00f5es do Couchbase Mobile. No Couchbase Mobile 1.x, os dados bin\u00e1rios eram armazenados na forma de \"anexos\" em um documento de n\u00edvel superior \"_anexos<\/em>\". O Couchbase Mobile introduziu o atributo bolha<\/a> para armazenar dados bin\u00e1rios. Na maioria dos casos, a discrep\u00e2ncia entre as representa\u00e7\u00f5es nas vers\u00f5es \u00e9 perfeitamente tratada pelo Couchbase Mobile, de modo que os usu\u00e1rios finais n\u00e3o precisam fazer nada de especial em seus aplicativos para lidar com isso. No entanto, h\u00e1 certos casos em que os desenvolvedores de aplicativos precisam tomar medidas adicionais para lidar com a discrep\u00e2ncia. Tamb\u00e9m discutiremos essas medidas nesta postagem e tentaremos responder a algumas perguntas frequentes.<\/p>\n

Fluxo de trabalho #1: manipula\u00e7\u00e3o de anexos criados no Couchbase Lite<\/h2>\n

Vamos dar uma olhada em como voc\u00ea pode criar documentos JSON com anexos de dados bin\u00e1rios com o Couchbase Lite e sincroniz\u00e1-los com o lado do servidor. Este \u00e9 o fluxo que estaremos descrevendo:<\/p>\n

\"\"<\/figure>\n

Criar anexos de dados bin\u00e1rios no Couchbase Lite<\/h3>\n

Os desenvolvedores devem usar o API de blob<\/a> para criar dados de blob. Um documento pode ser associado a um ou mais anexos ou blobs. Aqui est\u00e1 um trecho de c\u00f3digo que mostra o uso dessa API no Swift. Consulte a documenta\u00e7\u00e3o do desenvolvedor para obter trechos de c\u00f3digo equivalentes para outras plataformas.<\/p>\n

\r\n let mutableDoc = MutableDocument.init(id: \"user::priya\")\r\n if let profileImage = UIImage(named: \"profile.jpg\"), let imageData = UIImageJPEGRepresentation(profileImage, 0.75) {\r\n   let blob = Blob(contentType: \"image\/jpeg\", data: imageData)\r\n   mutableDoc.setBlob(blob, forKey: \"image\")\r\n }\r\n \/\/ \u2026 Add other properties\r\n mutableDoc.setString(\"user\", forKey: \"type\")\r\n mutableDoc.setString(\"Priya\", forKey: \"name\")\r\n mutableDoc.setString(\"priya.rajagopal@couchbase.com, forKey: \"email\")\r\n do {\r\n   try? db.saveDocument(mutableDoc)\r\n }\r\n catch {\r\n   print(\"Error in saving document : (error)\")\r\n }\r\n<\/code><\/pre>\n
Representa\u00e7\u00e3o interna<\/h3>\n
Quando o documento \u00e9 criado no Couchbase Lite, internamente, ele tem a seguinte apar\u00eancia:<\/p>\n
{\r\n  \"email\": \"priya.rajagopal@couchbase.com\",\r\n  \"image\": {\r\n   \"length\": 3888349,\r\n   \"digest\": \"sha1\u20134xlj1AKFgLdzcD7a1pVChrVTJIc=\",\r\n   \"content_type\": \"image\/jpeg\",\r\n   \"@type\": \"blob\"\r\n  },\r\n \"type\": \"user\",\r\n \"name\": \"Priya\",\r\n \"id\": \"user::priya\",\r\n \"rev\": \"1\u20131c8502034001b333cc469fe8c4c39e112eedf8a3\"\r\n}<\/code><\/pre>\n
Observe o \"@type\": \"blob\" <\/em>criado para os dados do tipo de imagem.<\/p>\n
Observa\u00e7\u00e3o<\/strong> que existem v\u00e1rios metadados em n\u00edvel de sistema, como _id<\/em> que est\u00e3o inclu\u00eddos no documento. Por quest\u00f5es de brevidade, nem tudo \u00e9 mostrado no exemplo. Os aplicativos nunca devem fazer suposi\u00e7\u00f5es sobre o formato e a disponibilidade dos metadados em n\u00edvel de sistema e, por esse motivo, nunca devem acessar esses atributos diretamente. Sempre use as op\u00e7\u00f5es de recupera\u00e7\u00e3o de metadados, como meta().id<\/em>.<\/p>\n
Sincroniza\u00e7\u00e3o de anexos com o Sync Gateway<\/h3>\n
O Sync Gateway \u00e9 compat\u00edvel com vers\u00f5es anteriores do Couchbase Mobile 1.x. Isso significa que o Sync Gateway precisa ser capaz de processar dados bin\u00e1rios usando a vers\u00e3o 1.x _. anexos<\/em> bem como a representa\u00e7\u00e3o de estilo 2.x bolha<\/em> tipo. Isso tamb\u00e9m implica que, quando o cliente Couchbase Lite 2.x envia dados para o Sync Gateway, ele precisa envi\u00e1-los em um formato compat\u00edvel com os clientes 1.x.<\/p>\n
Por esse motivo, quando o Couchbase Lite sincroniza o documento com o Sync Gateway, ele adiciona a tag _<\/em><\/strong>anexos\u00a0<\/em>entrada no documento. Portanto, o documento, quando enviado para cima, seria parecido com o exemplo abaixo. A lista de anexos associados ao documento \u00e9 especificada no campo _anexos<\/em> objeto.<\/p>\n
{\r\n  \"attachments\": {\r\n  \"blob\/image\": {\r\n   \"content_type\": \"image\/jpeg\",\r\n   \"digest\": \"sha1\u20134xlj1AKFgLdzcD7a1pVChrVTJIc=\",\r\n   \"length\": 3888349,\r\n   \"revpos\": 1,\r\n   \"stub\": true\r\n   }\r\n  },\r\n  \"email\": \"priya.rajagopal@couchbase.com\",\r\n  \"image\": {\r\n  \"@type\": \"blob\",\r\n  \"content_type\": \"image\/jpeg\",\r\n  \"digest\": \"sha1\u20134xlj1AKFgLdzcD7a1pVChrVTJIc=\",\r\n  \"length\": 3888349\r\n  },\r\n  \"name\": \"Priya\",\r\n  \"type\": \"user\",\r\n  \"id\": \"user::priya\",\r\n  \"rev\": \"1\u20131c8502034001b333cc469fe8c4c39e112eedf8a3\",\r\n}<\/code><\/em><\/pre>\n
Observa\u00e7\u00e3o<\/strong> que existem v\u00e1rios metadados em n\u00edvel de sistema, como _id<\/em> que est\u00e1 inclu\u00eddo no documento. Por quest\u00f5es de brevidade, nem tudo \u00e9 mostrado no exemplo. Os aplicativos nunca devem fazer suposi\u00e7\u00f5es sobre o formato e a disponibilidade dos metadados em n\u00edvel de sistema e, por esse motivo, nunca devem acessar esses atributos diretamente. Sempre use as op\u00e7\u00f5es de recupera\u00e7\u00e3o de metadados, como meta().id<\/em>.<\/p>\n
Recupera\u00e7\u00e3o de anexo no Sync Gateway<\/h3>\n
Os dados do anexo devem ser recuperados por meio do Sync Gateway _anexos<\/em> REST<\/a> endpoint. No momento da reda\u00e7\u00e3o deste post, os anexos n\u00e3o podem ser gerenciados diretamente usando os SDKs do Couchbase Server.<\/p>\n
Aqui est\u00e1 um exemplo de comando curl para recuperar o(s) anexo(s) associado(s) a um documento usando o comando _anexos<\/em> REST. Substitua o cabe\u00e7alho de autoriza\u00e7\u00e3o por credenciais adequadas correspondentes ao usu\u00e1rio configurado em seu sistema. Al\u00e9m disso, observe o nome do anexo, \"bolha_<\/em>%2Fimage” is the URL encoded version of \"blob<\/em>\/image\"_.<\/p>\n
curl -X GET \r\n 'https:\/\/sync-gateway-url:4984\/dbname\/user::priya\/blob_%2Fimage' \r\n -H 'Accept: application\/json' \r\n -H 'Authorization: Basic ZGVtbzpwYXNzd29yZA=='<\/code><\/pre>\n
Atualiza\u00e7\u00e3o de anexos no Sync Gateway<\/h3>\n
Os dados do anexo devem ser atualizados por meio do Sync Gateway _anexos<\/em> REST<\/a> endpoint. No momento da reda\u00e7\u00e3o deste post, os anexos m\u00f3veis n\u00e3o podem ser gerenciados usando os SDKs do Couchbase Server.<\/p>\n
Aqui est\u00e1 um exemplo de comando curl para atualizar um anexo associado a um documento usando o _anexos<\/em> REST. Voc\u00ea substituiria o cabe\u00e7alho de autoriza\u00e7\u00e3o por credenciais adequadas correspondentes ao usu\u00e1rio configurado em sua instala\u00e7\u00e3o. Al\u00e9m disso, observe que o cabe\u00e7alho \"rev\"<\/em> deve ser fornecido. Esse par\u00e2metro corresponde \u00e0 revis\u00e3o do documento que deve ser atualizado. Voc\u00ea pode recuperar o revId usando o par\u00e2metro GET documento REST<\/a>.<\/p>\n
 curl -i -X PUT 'https:\/\/sync-gateway-url:4984\/dbname\/user::priya\/blob_%2Fimage?rev=12-fa2bf00dab7e811eb562a502429ec633' \r\n -H 'Accept: application\/json' \r\n -H 'Authorization: Basic ZGVtbzE6cGFzc3dvcmQ=' \r\n -H 'Content-Type: image\/png' \r\n -H 'cache-control: no-cache' \r\n \u2013data-binary \"@layered.png\"<\/code><\/pre>\n
Mas... espere... uma incompatibilidade!<\/h3>\n
Agora, depois de atualizar o anexo, se voc\u00ea recuperar o documento usando o GET documento REST<\/a>,<\/p>\n
 curl -X GET \r\n 'https:\/\/sync-gateway-url:4984\/dbname\/user::priya\/blob_%2Fimage' \r\n -H 'Accept: application\/json' \r\n -H 'Authorization: Basic ZGVtbzE6cGFzc3dvcmQ=' \r\n -H 'Content-Type: application\/json' \r\n -H 'cache-control: no-cache'<\/code><\/pre>\n
A resposta correspondente seria algo parecido com isto:<\/p>\n
{\r\n  \"attachments\": {\r\n  \"blob\/image\": {\r\n   \"content_type\": \"image\/png\",\r\n   \"digest\": \"sha1-XeeXt0I014+1qpH+s2S2AUSg4II=\",\r\n   \"length\": 3444504,\r\n   \"revpos\": 16,\r\n   \"stub\": true\r\n   }\r\n  },\r\n  \"id\": \"user::demo1\",\r\n  \"rev\": \"13-e61d1a9e63069030212007a8b5eddde9\",\r\n  \"address\": \"\",\r\n  \"email\": \"demo1\",\r\n  \"image\": {\r\n   \"@type\": \"blob\",\r\n   \"content_type\": \"image\/jpeg\",\r\n   \"digest\": \"sha1\u20134xlj1AKFgLdzcD7a1pVChrVTJIc=\",\r\n   \"length\": 3888349\r\n  },\r\n  \"name\": \"Priya Rajagopal\",\r\n  \"type\": \"user\"\r\n}<\/code><\/pre>\n
Voc\u00ea perceber\u00e1 que o _Anexo<\/em> e bolha<\/em> n\u00e3o coincidem. Enquanto o _Anexo<\/em> aponta para a imagem mais recente, a entrada bolha<\/em> ainda descreve a imagem antiga. Mas tudo bem<\/em>!<\/p>\n
O motivo dessa discrep\u00e2ncia \u00e9 o fato de o Sync Gateway lidar apenas com anexos do estilo 1.x.<\/p>\n
Ent\u00e3o, como isso ainda funciona?<\/p>\n
Isso funciona porque, no contexto do Sync Gateway que lida com anexos no estilo 1.x, somente a entrada do anexo \u00e9 honrada.<\/p>\n
Mas e quanto ao Couchbase Lite? O que acontece quando o documento atualizado \u00e9 sincronizado pelo cliente Couchbase Lite 2.x?<\/p>\n
Quando o documento \u00e9 replicado pelo cliente do Couchbase Lite 2.x, o Couchbase Lite procura a presen\u00e7a de _anexos<\/em> e bolhas<\/em> dentro do documento e implementa a l\u00f3gica 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<\/em> como o anexo \"real\" e unifica a entrada de bolha correspondente.<\/p>\n
Do ponto de vista do desenvolvedor, tudo isso \u00e9 tratado automaticamente. Portanto, voc\u00ea n\u00e3o precisa se preocupar com nenhum dos detalhes. Como desenvolvedor, voc\u00ea teria que saber como recuperar o anexo atualizado de dentro do aplicativo habilitado para o Couchbase Lite.<\/p>\n
Recupera\u00e7\u00e3o de anexos atualizados no Couchbase Lite<\/h3>\n
Quando o anexo atualizado for sincronizado com seu aplicativo Couchbase Lite, use o comando API de blob<\/a> para recuperar os dados. Aqui est\u00e1 um trecho de c\u00f3digo que mostra o uso dessa API em swift. Consulte a documenta\u00e7\u00e3o do desenvolvedor para obter trechos de c\u00f3digo equivalentes para outras plataformas.<\/p>\n
\r\n if let doc = db.document(withID: \"user::priya\") {\r\n     let blobValue = doc.blob(forKey:\"image\")?.content\r\n     \/\/ use the blobValue\r\n }\r\n<\/code><\/pre>\n
Agora vamos dar uma olhada no fluxo inverso.<\/p>\n
Fluxo de trabalho #2: manipula\u00e7\u00e3o de anexos criados no Sync Gateway<\/h2>\n
Vamos dar uma olhada em como voc\u00ea pode criar documentos JSON com anexos de dados bin\u00e1rios no Sync Gateway e sincroniz\u00e1-los com o lado do Couchbase Lite.
\nEsse \u00e9 o fluxo que estaremos descrevendo.<\/p>\n
\"\"<\/figure>\n
Criar anexos de dados bin\u00e1rios no servidor<\/h3>\n
Para anexar dados bin\u00e1rios no lado do Couchbase Server que podem ser sincronizados com os clientes por meio do Sync Gateway, voc\u00ea teria que usar o Sync Gateway ponto de extremidade REST dos anexos<\/a>. No momento da reda\u00e7\u00e3o deste post, os anexos compat\u00edveis com dispositivos m\u00f3veis n\u00e3o podem ser criados diretamente usando os SDKs do Couchbase Server. Os dados do anexo criados por meio do endpoint REST do Sync Gateway s\u00e3o mantidos no bucket do Couchbase Server e sincronizados com os clientes do Couchbase Lite, sujeitos \u00e0s pol\u00edticas de controle de acesso configuradas no Sync Gateway.<\/p>\n
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\u00ea poderia criar um documento de v\u00e1rias partes com dados JSON e bin\u00e1rios. Mas isso pode ser tedioso, pois voc\u00ea tamb\u00e9m precisaria gerar os metadados relevantes do anexo. Portanto, as etapas descritas abaixo s\u00e3o a minha op\u00e7\u00e3o preferida<\/p>\n