Incorporación de blobs a objetos en Azure Digital Twins

Artículo
01/10/2020

Importante

Se ha publicado una nueva versión del servicio Azure Digital Twins. A la luz de las funcionalidades expandidas del nuevo servicio, se ha retirado el servicio Azure Digital Twins original (descrito en este conjunto de documentación).

Para ver la documentación del nuevo servicio, visite la documentación activa de Azure Digital Twins.

Los blobs son representaciones no estructuradas de tipos de archivo comunes (por ejemplo, imágenes y registros). Los blobs realizan un seguimiento del tipo de datos que representan mediante un tipo MIME (por ejemplo: "image/jpeg") y los metadatos (nombre, descripción, tipo, etc.).

Azure Digital Twins admite la conexión de blobs a dispositivos, espacios y usuarios. Los blobs pueden representar una imagen de perfil de un usuario, una foto de dispositivo, un vídeo, un mapa, un archivo zip de firmware, datos de JSON, un registro, etc.

En este artículo, se da por hecho que está familiarizado con la autenticación mediante las API de administración de Azure Digital Twins.

Para obtener más información sobre cómo autenticarse con las API de administración, consulte Autenticarse con las API de Azure Digital Twins.
Para autenticarse con las API de administración mediante el cliente de REST de Postman, vea Configuración de Postman.

Introducción a la carga de blobs

Las solicitudes de varias partes se usan para cargar blobs en puntos de conexión específicos y sus respectivas funcionalidades.

Nota:

Las solicitudes de varias partes normalmente requieren tres elementos:

Un encabezado Content-Type :
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Una disposición de contenido:
- form-data; name="metadata"
El contenido del archivo que se va a cargar

Content-Type y Content-Disposition variarán en función del escenario de uso.

Se pueden realizar solicitudes de varias partes mediante programación (a través de C#), a través de un cliente de REST o de una herramienta como Postman. Las herramientas de cliente REST pueden tener distintos niveles de compatibilidad de las solicitudes complejas con varias partes. Las opciones de configuración también pueden variar ligeramente de una herramienta a otra. Compruebe qué herramienta se adapta mejor a sus necesidades.

Importante

Las solicitudes de varias partes realizadas a las API de administración de Azure Digital Twins normalmente tienen dos partes:

los metadatos del blob (como un tipo MIME asociado) declarado por Content-Type o Content-Disposition.
Contenido del blob que incluye el contenido no estructurado de un archivo que se cargará

Ninguna de las dos partes es necesaria para las solicitudes PATCH. Ambos son necesarios para las operaciones de creación o POST.

El código fuente de inicio rápido de ocupación contiene completos ejemplos de C# que muestran cómo realizar solicitudes de varias partes en las API de administración de Azure Digital Twins.

Metadatos de blob

Además de Content-Type y Content-Disposition, las solicitudes de varias partes de blobs de Azure Digital Twins deben especificar el cuerpo JSON correcto. El cuerpo JSON que se enviará depende del tipo de operación de solicitud HTTP que se esté realizando.

Los cuatro esquemas JSON principales utilizados son:

Los metadatos del blob JSON se ajustan al modelo siguiente:

{
    "parentId": "00000000-0000-0000-0000-000000000000",
    "name": "My First Blob",
    "type": "Map",
    "subtype": "GenericMap",
    "description": "A well chosen description",
    "sharing": "None"
  }

Attribute	Tipo	Descripción
parentId	Cadena	Entidad primaria con la que se asocia el blob (espacios, dispositivos o usuarios)
name	Cadena	Nombre fácil de usar para el blob
type	String	Tipo de blob, no se puede usar type ni typeId
typeId	Entero	Id. de tipo de blob, no se puede usar type ni typeId
subtype	Cadena	Subtipo de blob, no se puede usar subtype ni subtypeId
subtypeId	Entero	Id. de subtipo del blob, no se puede usar subtype ni subtypeId
descripción	Cadena	Descripción personalizada del blob
sharing	Cadena	Si el blob se puede compartir, enum [`None`, `Tree`, `Global`]

Los metadatos del blob siempre se proporcionan como el primer fragmento con Content-Type application/json o como archivo .json. Los datos de archivos se proporcionan en el segundo fragmento y pueden ser de cualquier tipo MIME admitido.

La documentación de Swagger describe estos esquemas de modelo con detalle.

Sugerencia

Se proporciona un preestreno de Swagger para demostrar el conjunto de características de la API. Se hospeda en docs.westcentralus.azuresmartspaces.net/management/swagger.

Puede acceder a su propia documentación de Management API generada con Swagger en:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger

Nombre	Reemplazar por
YOUR_INSTANCE_NAME	El nombre de la instancia de Azure Digital Twins
YOUR_LOCATION	La región de servidor en la que está hospedada la instancia

Para obtener información sobre el uso de la documentación de referencia, lea el artículo sobre cómo usar Swagger.

Datos de respuesta de blobs

Los blobs devueltos individualmente cumplen con el esquema JSON siguiente:

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "parentId": "00000000-0000-0000-0000-000000000000",
  "type": "string",
  "subtype": "string",
  "typeId": 0,
  "subtypeId": 0,
  "sharing": "None",
  "description": "string",
  "contentInfos": [
    {
      "type": "string",
      "sizeBytes": 0,
      "mD5": "string",
      "version": "string",
      "lastModifiedUtc": "2019-01-12T00:58:08.689Z",
      "metadata": {
        "additionalProp1": "string",
        "additionalProp2": "string",
        "additionalProp3": "string"
      }
    }
  ],
  "fullName": "string",
  "spacePaths": [
    "string"
  ]
}

Attribute	Tipo	Descripción
id	Cadena	Identificador único para el blob
name	Cadena	Nombre fácil de usar para el blob
parentId	Cadena	Entidad primaria con la que se asocia el blob (espacios, dispositivos o usuarios)
type	String	Tipo de blob, no se puede usar type ni typeId
typeId	Entero	Id. de tipo de blob, no se puede usar type ni typeId
subtype	Cadena	Subtipo de blob, no se puede usar subtype ni subtypeId
subtypeId	Entero	Id. de subtipo del blob, no se puede usar subtype ni subtypeId
sharing	Cadena	Si el blob se puede compartir, enum [`None`, `Tree`, `Global`]
descripción	Cadena	Descripción personalizada del blob
contentInfos	Matriz	Especifica la información de metadatos sin estructurar, incluida la versión
fullName	Cadena	Nombre completo del blob
spacePaths	Cadena	Ruta de acceso al espacio

Ejemplos de solicitud de varias partes del blob

En los ejemplos siguientes, YOUR_MANAGEMENT_API_URL hace referencia al identificador URI de la API de Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0

Nombre	Reemplazar por
YOUR_INSTANCE_NAME	El nombre de la instancia de Azure Digital Twins
YOUR_LOCATION	La región en la que está hospedada la instancia

Para cargar un archivo de texto como blob y asociarlo a un espacio, realice una solicitud HTTP POST autenticada a:

YOUR_MANAGEMENT_API_URL/spaces/blobs

Con el siguiente cuerpo:

--USER_DEFINED_BOUNDARY
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data; name="metadata"

{
  "ParentId": "54213cf5-285f-e611-80c3-000d3a320e1e",
  "Name": "My First Blob",
  "Type": "Map",
  "SubType": "GenericMap",
  "Description": "A well chosen description",
  "Sharing": "None"
}
--USER_DEFINED_BOUNDARY
Content-Disposition: form-data; name="contents"; filename="myblob.txt"
Content-Type: text/plain

This is my blob content. In this case, some text, but I could also be uploading a picture, an JSON file, a firmware zip, etc.

--USER_DEFINED_BOUNDARY--

Valor	Reemplazar por
USER_DEFINED_BOUNDARY	Nombre de un límite de contenido de varias partes

El siguiente código es una implementación de .NET de la misma carga de blobs mediante la clase MultipartFormDataContent:

//Supply your metadata in a suitable format
var multipartContent = new MultipartFormDataContent("USER_DEFINED_BOUNDARY");

var metadataContent = new StringContent(JsonConvert.SerializeObject(metaData), Encoding.UTF8, "application/json");
metadataContent.Headers.ContentType = MediaTypeHeaderValue.Parse("application/json; charset=utf-8");
multipartContent.Add(metadataContent, "metadata");

//MY_BLOB.txt is the String representation of your text file
var fileContents = new StringContent("MY_BLOB.txt");
fileContents.Headers.ContentType = MediaTypeHeaderValue.Parse("text/plain");
multipartContent.Add(fileContents, "contents");

var response = await httpClient.PostAsync("spaces/blobs", multipartContent);

Por último, los usuarios de cURL pueden hacer solicitudes de formulario de varias partes de la misma manera:

curl -X POST "YOUR_MANAGEMENT_API_URL/spaces/blobs" \
 -H "Authorization: Bearer YOUR_TOKEN" \
 -H "Accept: application/json" \
 -H "Content-Type: multipart/form-data" \
 -F "meta={\"ParentId\":\"YOUR_SPACE_ID\",\"Name\":\"My CURL Blob\",\"Type\":\"Map\",\"SubType\":\"GenericMap\",\"Description\":\"A well chosen description\",\"Sharing\":\"None\"};type=application/json" \
 -F "text=PATH_TO_FILE;type=text/plain"

Valor	Reemplazar por
YOUR_TOKEN	El token de OAuth 2.0 válido
YOUR_SPACE_ID	El identificador del espacio con el cual asociar el blob
PATH_TO_FILE	La ruta de acceso al archivo de texto

Una publicación correcta devuelve el identificador del nuevo blob.

Puntos de conexión de API

Las siguientes secciones describen los principales puntos de conexión de API relacionados con el blob y sus funcionalidades.

Dispositivos

Puede conectar blobs a dispositivos. La siguiente imagen muestra la documentación de referencia de Swagger para las API de administración. Especifica los puntos de conexión de API relacionados con los dispositivos para el consumo de blobs y los parámetros de ruta de acceso necesarios que se pasarán a dichos puntos de conexión.

Por ejemplo, para actualizar o crear un blob y conectarlo a un dispositivo, realice una solicitud HTTP PATCH autenticada a:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

Parámetro	Reemplazar por
YOUR_BLOB_ID	Identificador de blob deseado

Las solicitudes correctas devuelven un objeto JSON como se ha descrito anteriormente.

Espacios

También puede conectar blobs a espacios. En la imagen siguiente se enumeran todos los puntos de conexión de API de espacio responsables de controlar los blobs. También muestra los parámetros de ruta de acceso que se van a pasar a esos puntos de conexión.

Por ejemplo, para devolver un blob conectado a un espacio, realice una solicitud HTTP GET autenticada a:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

Parámetro	Reemplazar por
YOUR_BLOB_ID	Identificador de blob deseado

Las solicitudes correctas devuelven un objeto JSON como se ha descrito anteriormente.

Una solicitud PATCH al mismo punto de conexión actualiza las descripciones de metadatos y crea versiones del blob. La solicitud HTTP se realiza mediante el método PATCH, con los metadatos y los datos de formulario de varias partes necesarios.

Usuarios

Puede conectar blobs a modelos de usuario (por ejemplo, para asociar una imagen de perfil). En la imagen siguiente se muestran los puntos de conexión de API de usuarios pertinentes y los parámetros de ruta de acceso necesarios, como id:

Por ejemplo, para capturar un blob conectado a un usuario, realice una solicitud HTTP GET autenticada con todos los datos de formulario necesarios a:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

Parámetro	Reemplazar por
YOUR_BLOB_ID	Identificador de blob deseado

Las solicitudes correctas devuelven un objeto JSON como se ha descrito anteriormente.

Errores comunes

Un error común incluye no suministrar la información de encabezado correcta:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
Para resolver este error, verifique que la solicitud general tenga un encabezado Content-Type adecuado:
- multipart/mixed
- multipart/form-data
Además, verifique que cada fragmento de varias partes tenga un Content-Type correspondiente apropiado.
Se produce un segundo error habitual cuando se asignan varios blobs al mismo recurso en el gráfico de inteligencia espacial:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Nota:

El atributo mensaje variará en función del recurso.

Solo se puede adjuntar un blob (de cada tipo) a cada recurso del gráfico espacial.

Para resolver este error, actualice el blob existente mediante la operación HTTP PATCH adecuada de la API. Si lo hace, reemplazará los datos del blob existentes por los datos deseados.

Pasos siguientes

Para obtener más información sobre la documentación de referencia de Swagger para Azure Digital Twins, lea Uso de Azure Digital Twins Swagger.
Para cargar blobs a través de Postman, lea Configuración de Postman.

Compartir a través de

Incorporación de blobs a objetos en Azure Digital Twins

Introducción a la carga de blobs

Metadatos de blob

Datos de respuesta de blobs

Ejemplos de solicitud de varias partes del blob

Puntos de conexión de API

Dispositivos

Espacios

Usuarios

Errores comunes

Pasos siguientes

Recursos adicionales