IBM Cloud Docs
Cómo utilizar archivos adjuntos

Cómo utilizar archivos adjuntos

Otra forma de almacenar datos consiste en utilizar adjuntos. Los archivos adjuntos son objeto binario grande (BLOB) que se incluyen en los documentos.

Se recomienda mantener los archivos adjuntos pequeños en tamaño y número porque los archivos adjuntos pueden afectar al rendimiento.

El BLOB se almacena en el componente _attachments del documento. El BLOB contiene datos que incluyen la siguiente información:

  • El nombre del adjunto
  • El tipo de adjunto
  • El contenido real

Imágenes y archivos multimedia serían ejemplos de BLOB.

Si incluye el adjunto como un componente en línea del JSON global, el contenido del adjunto se representa utilizando el formulario BASE64.

El tipo de contenido corresponde a un tipo MIME. Por ejemplo, si desea adjuntar un archivo de imagen .jpg a un documento, especifique el tipo MIME del adjunto como image/jpeg.

Los archivos adjuntos no están permitidos en documentos en bases de datos _replicator o _users .

Crear o actualizar

Para crear un nuevo adjunto al mismo tiempo que se crea un nuevo documento, incluya el archivo adjunto como un componente en línea del contenido JSON.

Para crear un nuevo adjunto en un documento existente, o para actualizar un adjunto en un documento, realice una solicitud PUT con el valor _rev más reciente del documento en https://$ACCOUNT.cloudant.com/$DATABASE/$DOCUMENT_ID/$ATTACHMENT. El tipo de contenido del archivo adjunto debe especificarse utilizando la cabecera Content-Type . El valor de $ATTACHMENT es el nombre con el que el adjunto está asociado al documento.

Puede crear más de un adjunto para un documento asegurándose de que el valor de $ATTACHMENT para cada adjunto sea exclusivo dentro del documento.

Consulte el ejemplo siguiente para crear o actualizar un archivo adjunto mediante HTTP:

PUT /$DATABASE/$DOCUMENT_ID/$ATTACHMENT?rev=$REV HTTP/1.1
Content-Type: $$ATTACHMENT_MIME_TYPE

Consulte el ejemplo siguiente para crear o actualizar un archivo adjunto:

curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X PUT "$SERVICE_URL/products/small-appliances:100001/product_details.txt" -H "Content-Type: text/plain" --data 'This appliance includes...'

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DocumentResult;
import com.ibm.cloud.cloudant.v1.model.PutAttachmentOptions;

import java.io.ByteArrayInputStream;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;

Cloudant service = Cloudant.newInstance();

String detailedDescription = "This appliance includes...";

InputStream detailedDescriptionStream =
    new ByteArrayInputStream(detailedDescription
        .getBytes(StandardCharsets.UTF_8));

PutAttachmentOptions attachmentOptions =
    new PutAttachmentOptions.Builder()
        .db("products")
        .docId("small-appliances:100001")
        .attachmentName("product_details.txt")
        .attachment(detailedDescriptionStream)
        .contentType("text/plain")
        .build();

DocumentResult response =
    service.putAttachment(attachmentOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

const stream = new Readable();
stream.push('This appliance includes...');
stream.push(null);

service.putAttachment({
  db: 'products',
  docId: 'small-appliances:100001',
  attachmentName: 'product_details.txt',
  attachment: stream,
  contentType: 'text/plain'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

detailed_description = "This appliance includes..."
response = service.put_attachment(
  db='products',
  doc_id='small-appliances:100001',
  attachment_name='product_details.txt',
  attachment=detailed_description,
  content_type='text/plain'
).get_result()

print(response)

putAttachmentOptions := service.NewPutAttachmentOptions(
  "products",
  "small-appliances:100001",
  "product_details.txt",
  ioutil.NopCloser(
    bytes.NewReader([]byte("This appliance includes...")),
  ),
  "text/plain",
)

documentResult, response, err := service.PutAttachment(putAttachmentOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(documentResult, "", "  ")
fmt.Println(string(b))

El ejemplo Go anterior requiere el siguiente bloque de importación:

import (
   "encoding/json"
   "fmt"
   "io/ioutil"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte la sección de autenticación en la documentación de la API para obtener ejemplos.

La respuesta incluye el ID del documento y la nueva revisión del documento.

Los adjuntos no tienen sus propias revisiones. En lugar de esto, al actualizar o crear un archivo adjunto, la revisión del documento se adjunta a los cambios.

Consulte la siguiente respuesta de ejemplo con el ID del documento y la nueva revisión:

{
	"id" : "FishStew",
	"ok" : true,
	"rev" : "9-247bb19a41bfd9bfdaf5ee6e2e05be74"
}

Leer

Para recuperar un adjunto, realice una solicitud GET en https://$ACCOUNT.cloudant.com/$DATABASE/$DOCUMENT_ID/$ATTACHMENT. El cuerpo de la respuesta es el contenido sin formato del archivo adjunto.

Consulte el ejemplo siguiente de lectura de un archivo adjunto mediante HTTP:

GET /$DATABASE/$DOCUMENT_ID/$ATTACHMENT HTTP/1.1

Consulte el siguiente ejemplo de lectura de un archivo adjunto:

curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X GET "$SERVICE_URL/products/small-appliances:100001/product_details.txt"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.GetAttachmentOptions;

import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.util.stream.Collectors;

Cloudant service = Cloudant.newInstance();

GetAttachmentOptions attachmentOptions =
    new GetAttachmentOptions.Builder()
        .db("products")
        .docId("small-appliances:100001")
        .attachmentName("product_details.txt")
        .build();

InputStream streamResult =
    service.getAttachment(attachmentOptions).execute()
        .getResult();

String response =
    new BufferedReader(new InputStreamReader(streamResult))
        .lines().collect(Collectors.joining("\n"));

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.getAttachment({
  db: 'products',
  docId: 'small-appliances:100001',
  attachmentName: 'product_details.txt'
}).then(response => {
  let attachment = response.result as Readable;
  attachment.pipe(process.stdout);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response_attachment = service.get_attachment(
  db='products',
  doc_id='small-appliances:100001',
  attachment_name='product_details.txt'
).get_result().content

print(response_attachment)

getAttachmentOptions := service.NewGetAttachmentOptions(
  "products",
  "small-appliances:100001",
  "product_details.txt",
)

result, response, err := service.GetAttachment(getAttachmentOptions)
if err != nil {
  panic(err)
}

data, _ := ioutil.ReadAll(result)
fmt.Println("\n", string(data))

El ejemplo Go anterior requiere el siguiente bloque de importación:

import (
   "fmt"
   "io/ioutil"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Suprimir un adjunto

Para suprimir un archivo adjunto, realice una solicitud DELETE con el archivo _rev más reciente del documento. a https://$ACCOUNT.cloudant.com/$DATABASE/$DOCUMENT_ID/$ATTACHMENT. Si no proporciona el _revmás reciente, la respuesta es un error 409.

Consulte el ejemplo siguiente para suprimir un archivo adjunto mediante HTTP:

DELETE /$DATABASE/$DOCUMENT_ID/$ATTACHMENT?rev=$REV HTTP/1.1

Consulte el siguiente ejemplo de supresión de un archivo adjunto:

curl -H "Authorization: Bearer $API_BEARER_TOKEN" -X DELETE "$SERVICE_URL/products/small-appliances:100001/product_details.txt?rev=4-1a0d1cd6f40472509e9aac646183736a"

import com.ibm.cloud.cloudant.v1.Cloudant;
import com.ibm.cloud.cloudant.v1.model.DeleteAttachmentOptions;
import com.ibm.cloud.cloudant.v1.model.DocumentResult;

Cloudant service = Cloudant.newInstance();

DeleteAttachmentOptions attachmentOptions =
    new DeleteAttachmentOptions.Builder()
        .db("products")
        .docId("small-appliances:100001")
        .attachmentName("product_details.txt")
        .rev("4-1a0d1cd6f40472509e9aac646183736a")
        .build();

DocumentResult response =
    service.deleteAttachment(attachmentOptions).execute()
        .getResult();

System.out.println(response);

const { CloudantV1 } = require('@ibm-cloud/cloudant');

const service = CloudantV1.newInstance({});

service.deleteAttachment({
  db: 'products',
  docId: 'small-appliances:100001',
  attachmentName: 'product_details.txt',
  rev: '4-1a0d1cd6f40472509e9aac646183736a'
}).then(response => {
  console.log(response.result);
});

from ibmcloudant.cloudant_v1 import CloudantV1

service = CloudantV1.new_instance()

response = service.delete_attachment(
  db='products',
  doc_id='small-appliances:100001',
  attachment_name='product_details.txt',
  rev='4-1a0d1cd6f40472509e9aac646183736a'
).get_result()

print(response)

deleteAttachmentOptions := service.NewDeleteAttachmentOptions(
  "products",
  "small-appliances:100001",
  "product_details.txt",
)
deleteAttachmentOptions.SetRev("4-1a0d1cd6f40472509e9aac646183736a")

documentResult, response, err := service.DeleteAttachment(deleteAttachmentOptions)
if err != nil {
  panic(err)
}

b, _ := json.MarshalIndent(documentResult, "", "  ")
fmt.Println(string(b))

El ejemplo Go anterior requiere el siguiente bloque de importación:

import (
   "encoding/json"
   "fmt"
   "github.com/IBM/cloudant-go-sdk/cloudantv1"
)

Todos los ejemplos de Go requieren que se inicialice el objeto service. Para obtener más información, consulte los ejemplos de la Sección de autenticación de la documentación de la API.

Si la supresión se realiza correctamente, la respuesta incluye "ok": true y el ID y la nueva revisión del documento.

Consulte la siguiente respuesta de ejemplo después de una supresión correcta de un archivo adjunto:

{
	"ok": true,
	"id": "DocID",
	"rev": "3-aedfb06537c1d77a087eb295571f7fc9"
}

En línea

Los adjuntos en línea son archivos adjuntos que se incluyen como parte del contenido JSON. El contenido debe proporcionarse utilizando la representación BASE64 , tal como se muestra en el ejemplo.

Encontrará una lista completa de tipos de soporte en el artículo tipos de soporte .

Consulte el siguiente documento JSON de ejemplo que incluye un adjunto en línea de una imagen jpeg:

{
	"_id":"document_with_attachment",
	"_attachments":
	{
		"name_of_attachment": {
			"content_type":"image/jpeg",
			"data": "iVBORw0KGgoAA... ...AASUVORK5CYII="
		}
	}
}

Consideraciones sobre el rendimiento

Aunque los archivos adjuntos resultan útiles, afectan al rendimiento de la aplicación. En concreto, el hecho de tener demasiados archivos adjuntos puede afectar negativamente al rendimiento durante la réplica.

Por ejemplo, si la aplicación requiere almacenamiento para varias imágenes como archivos adjuntos o incluye imágenes grandes, debe utilizar un mecanismo de almacenamiento BLOB alternativo para almacenar las imágenes. Puede utilizar IBM Cloudant para conservar los metadatos de imagen, como por ejemplo URL para el almacén BLOB.

Es posible que le resulte útil realizar pruebas de rendimiento para su aplicación específica para determinar qué enfoque funciona mejor en su caso.