Aggiungere BLOB agli oggetti in Gemelli digitali di Azure

Articolo
01/10/2020

Importante

È stata rilasciata una nuova versione del servizio Gemelli digitali di Azure. Alla luce delle funzionalità espanse del nuovo servizio, il servizio Gemelli digitali di Azure originale (descritto in questo set di documentazione) è stato ritirato.

Per visualizzare la documentazione per il nuovo servizio, vedere la documentazione attiva di Gemelli digitali di Azure.

I BLOB sono rappresentazioni non strutturate di tipi di file comuni, ad esempio immagini e log. I BLOB tengono traccia del tipo di dati che rappresentano tramite l'uso di un tipo MIME (ad esempio "image/jpeg") e dei metadati (nome, descrizione, tipo e così via).

Gemelli digitali di Azure supporta il collegamento dei BLOB a dispositivi, spazi e utenti. I BLOB possono rappresentare un'immagine del profilo di un utente, una foto del dispositivo, un video, una mappa, un file zip del firmware, dati JSON, un log, ecc.

Questo articolo presuppone una certa familiarità con l'autenticazione con le API di gestione di Gemelli digitali di Azure.

Per altre informazioni sull'autenticazione con le API di gestione, vedere Autenticazione con le API di Gemelli digitali di Azure.
Per eseguire l'autenticazione con le API di gestione usando il client REST di Postman, leggere Come configurare Postman.

Panoramica sul caricamento dei BLOB

È possibile usare richieste multipart per caricare i BLOB e le relative funzionalità in endpoint specifici.

Nota

Per le richieste multipart in genere sono necessari tre elementi:

Intestazione Content-Type :
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Disposizione del contenuto:
- form-data; name="metadata"
Il contenuto del file da caricare

Il contenuto di Content-Type e Content-Disposition varia in base allo scenario.

Le richieste multipart possono essere effettuate a livello di programmazione (tramite C#), mediante un client REST o con uno strumento come Postman. Gli strumenti client REST possono avere vari livelli di supporto per le richieste multipart complesse. Le impostazioni di configurazione possono inoltre variare leggermente da strumento a strumento. Verificare quale strumento è più adatto alle proprie esigenze.

Importante

Le richieste multipart inviate alle API Gestione di Gemelli digitali di Azure sono in genere suddivise in due parti:

Metadati BLOB, ad esempio un tipo MIME associato, dichiarati da Content-Type e/o Content-Disposition
Contenuto BLOB che include il contenuto non strutturato di un file da caricare

Per le richieste PATCH non è necessaria nessuna delle due parti, mentre entrambe sono necessarie per le operazioni POST o di creazione.

Il codice sorgente dell'avvio rapido relativo all'occupazione contiene esempi C# completi che illustrano come effettuare richieste multipart alle API di gestione di Gemelli digitali di Azure.

Metadati BLOB

Oltre a Content-Type e Content-Disposition, le richieste multipart BLOB di Gemelli digitali di Azure devono specificare il corpo JSON corretto. Il corpo JSON da inviare dipende dal tipo di operazione di richiesta HTTP che viene eseguita.

I quattro schemi JSON principali sono i seguenti:

I metadati dei BLOB JSON sono conformi al modello seguente:

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

Attributo	Tipo	Descrizione
parentId	String	Entità padre a cui associare il BLOB (spazi, dispositivi o utenti)
name	string	Nome descrittivo per il BLOB
type	String	Tipo di BLOB: non è possibile usare type e typeId
typeId	Intero	ID del tipo di BLOB: non è possibile usare type e typeId
subtype	String	Sottotipo di BLOB: non è possibile usare type e subtypeId
subtypeId	Intero	ID del sottotipo di BLOB: non è possibile usare subtype e subtypeId
description	Stringa	Descrizione personalizzata del BLOB
sharing	String	Indica se il BLOB può essere condiviso: enumerazione [`None`, `Tree`, `Global`]

I metadati BLOB vengono sempre forniti come primo blocco con Content-Type application/json o come .json file. I dati dei file vengono specificati nel secondo blocco e possono essere di qualsiasi tipo MIME supportato.

La documentazione di Swagger descrive in dettaglio questi schemi del modello.

Suggerimento

Viene fornita un'anteprima di prova di Swagger per mostrare il set di funzionalità delle API. L'anteprima è ospitata in docs.westcentralus.azuresmartspaces.net/management/swagger.

È possibile accedere alla propria documentazione di Swagger generata automaticamente dell'API di gestione all'indirizzo:

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

Nome	Replace with
NOME_ISTANZA_UTENTE	Nome dell'istanza di Gemelli digitali di Azure
POSIZIONE_UTENTE	Area del server in cui è ospitata l'istanza

Per informazioni sull'uso della documentazione di riferimento, vedere Come usare Swagger.

Dati della risposta dei BLOB

I BLOB restituiti singolarmente sono conformi allo schema JSON seguente:

{
  "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"
  ]
}

Attributo	Tipo	Descrizione
id	String	Identificatore univoco per il BLOB
name	string	Nome descrittivo per il BLOB
parentId	String	Entità padre a cui associare il BLOB (spazi, dispositivi o utenti)
type	String	Tipo di BLOB: non è possibile usare type e typeId
typeId	Intero	ID del tipo di BLOB: non è possibile usare type e typeId
subtype	String	Sottotipo di BLOB: non è possibile usare type e subtypeId
subtypeId	Intero	ID del sottotipo di BLOB: non è possibile usare subtype e subtypeId
sharing	String	Indica se il BLOB può essere condiviso: enumerazione [`None`, `Tree`, `Global`]
description	Stringa	Descrizione personalizzata del BLOB
contentInfos	Matrice	Specifica le informazioni dei metadati non strutturati, inclusa la versione
fullName	String	Nome completo del BLOB
spacePaths	String	Percorso dello spazio

Esempi di richiesta multipart di BLOB

Negli esempi seguenti, YOUR_MANAGEMENT_API_URL fa riferimento all'URI delle API di Gemelli digitali:

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

Nome	Replace with
NOME_ISTANZA_UTENTE	Nome dell'istanza di Gemelli digitali di Azure
POSIZIONE_UTENTE	Area in cui è ospitata l'istanza

Per caricare un file di testo come BLOB e associarlo a uno spazio, inviare una richiesta HTTP POST autenticata al percorso seguente:

YOUR_MANAGEMENT_API_URL/spaces/blobs

Con il corpo seguente:

--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--

Valore	Replace with
USER_DEFINED_BOUNDARY	Nome di un limite di contenuto multipart

Il codice seguente è un'implementazione .NET dello stesso caricamento di BLOB tramite la classe 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);

Gli utenti di cURL possono infine eseguire richieste di moduli multipart nello stesso modo:

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"

Valore	Replace with
YOUR_TOKEN	Il proprio token OAuth 2.0 valido
YOUR_SPACE_ID	L'ID dello spazio a cui associare il BLOB
PATH_TO_FILE	Il percorso del file di testo

Un POST riuscito restituisce l'ID del nuovo BLOB.

Endpoint API

Le sezioni seguenti descrivono i principali endpoint API correlati ai BLOB e le relative funzionalità.

Dispositivi

È possibile associare i BLOB a dispositivi. L'immagine seguente illustra la documentazione di riferimento di Swagger per le API Gestione. Specifica gli endpoint API associati al dispositivo per l'uso di BLOB ed eventuali parametri di percorso richiesti da passare al loro interno.

Ad esempio, per aggiornare o creare un BLOB e collegarlo a un dispositivo inviare una richiesta HTTP PATCH autenticata al percorso seguente:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

Parametro	Replace with
YOUR_BLOB_ID	ID del BLOB desiderato

Le richieste con esito positivo restituiscono un oggetto JSON, come descritto in precedenza.

Spazi

È anche possibile associare i BLOB a spazi. L'immagine seguente elenca tutti gli endpoint API di spazi responsabili della gestione di BLOB. Elenca anche i parametri di percorso da passare in tali endpoint.

Ad esempio, per restituire un BLOB collegato a uno spazio, inviare una richiesta HTTP GET autenticata al percorso seguente:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

Parametro	Replace with
YOUR_BLOB_ID	ID del BLOB desiderato

Le richieste con esito positivo restituiscono un oggetto JSON, come descritto in precedenza.

Una richiesta PATCH allo stesso endpoint aggiorna le descrizioni dei metadati e crea le versioni del BLOB. La richiesta HTTP viene effettuata tramite il metodo PATCH con tutti i metadati e i dati modulo multipart necessari.

Utenti

È possibile collegare BLOB a modelli utente (ad esempio per associare un'immagine del profilo). L'immagine seguente illustra gli endpoint API utente pertinenti e i parametri di percorso necessari, ad esempio id:

Ad esempio, per recuperare un BLOB collegato a un utente, inviare una richiesta HTTP GET autenticata con tutti i dati modulo necessari:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

Parametro	Replace with
YOUR_BLOB_ID	ID del BLOB desiderato

Le richieste con esito positivo restituiscono un oggetto JSON, come descritto in precedenza.

Errori comuni

Un errore comune è quello di non specificare le informazioni di intestazione corrette:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
Per risolvere questo errore, verificare che la richiesta generale abbia un'intestazione Content-Type appropriata:
- multipart/mixed
- multipart/form-data
Verificare inoltre che ogni blocco multipart abbia un tipo di contenuto appropriato.
Un secondo errore comune si verifica quando più BLOB vengono assegnati alla stessa risorsa nel grafico di intelligenza spaziale:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Nota

L'attributo del messaggio varia in base alla risorsa.

Un solo BLOB (di ogni tipo) può essere collegato a ogni risorsa all'interno del grafico spaziale.

Per risolvere questo errore, aggiornare il BLOB esistente usando l'operazione PATCH HTTP API appropriata. In questo modo i dati BLOB esistenti verranno sostituiti con i dati desiderati.

Passaggi successivi

Per altre informazioni sulla documentazione di riferimento di Swagger per Gemelli digitali di Azure, vedere Usare Swagger per Gemelli digitali.
Per caricare i BLOB tramite Postman, vedere Come configurare Postman.

Condividi tramite

Aggiungere BLOB agli oggetti in Gemelli digitali di Azure

Panoramica sul caricamento dei BLOB

Metadati BLOB

Dati della risposta dei BLOB

Esempi di richiesta multipart di BLOB

Endpoint API

Dispositivi

Spazi

Utenti

Errori comuni

Passaggi successivi

Risorse aggiuntive