Hinzufügen von Blobs zu Objekten in Azure Digital Twins

Artikel
01/10/2020

Wichtig

Eine neue Version des Azure Digital Twins-Diensts wurde veröffentlicht. Angesichts der erweiterten Funktionen des neuen Diensts wurde der ursprüngliche Azure Digital Twins-Dienst (in diesem Dokumentationssatz beschrieben) eingestellt.

Um die Dokumentation für den neuen Dienst anzuzeigen, besuchen Sie die aktive Azure Digital Twins-Dokumentation.

Blobs sind unstrukturierte Darstellungen gängiger Dateitypen (z. B. Bilder oder Protokolle). Blobs verfolgen mithilfe eines MIME-Typs (beispielsweise „image/jpeg“) sowie Metadaten (Name, Beschreibung, Typ usw.) die Art der dargestellten Daten nach.

Azure Digital Twins unterstützt das Anfügen von Blobs an Geräte, Räume und Benutzer. Blobs können ein Profilbild für einen Benutzer, ein Gerätefoto, ein Video, eine Karte, ein Firmware-ZIP-Archiv, JSON-Daten, ein Protokoll o.ä. darstellen.

In diesem Artikel wird eine gewisse Vertrautheit mit der Authentifizierung bei den Azure Digital Twins-Verwaltungs-APIs vorausgesetzt.

Wenn Sie zur Authentifizierung mittels Ihrer Verwaltungs-APIs erfahren möchten, lesen Sie Authentifizierung mit Azure Digital Twins-APIs.
Informationen zum Authentifizieren mittels Ihrer Verwaltungs-APIs unter Verwendung des Postman REST-Clients finden Sie unter Gewusst wie: Konfigurieren von Postman.

Hochladen von Blobs – Übersicht

Sie können Blobs unter Verwendung mehrteiliger Anforderungen in bestimmte Endpunkte und deren jeweilige Funktionen hochladen.

Hinweis

Mehrteilige Anforderungen umfassen in der Regel drei Informationselemente:

Inhaltstypheader:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Eine Inhaltsverfügung:
- form-data; name="metadata"
Der hochzuladende Dateiinhalt

Content-Type und Content-Disposition variieren je nach Verwendungsszenario.

Mehrteilige Anforderungen können programmgesteuert vorgenommen werden (über C#), über einen REST-Client oder Tools wie z.B. Postman. REST-Clienttools weisen möglicherweise verschiedene Ebenen der Unterstützung für komplexe mehrteiligen Anforderungen auf. Konfigurationseinstellungen können von Tool zu Tool leicht variieren. Überprüfen Sie, welches Tool am besten für Ihre Anforderungen geeignet ist.

Wichtig

Mehrteilige Anforderungen an Verwaltungs-APIs von Azure Digital Twins bestehen normalerweise aus zwei Teilen:

Blobmetadaten (z.B. ein zugeordneter MIME-Typ), der von Content-Type und/oder Content-Disposition deklariert wird.
Blobinhalt einschließlich der unstrukturierten Inhalte einer hochzuladenden Datei

Bei PATCH-Anforderungen wird keiner der beiden Teile benötigt. Bei POST- oder Erstellungsvorgängen werden dagegen beide Teile benötigt.

Der Occupancy Quickstart-Quellcode enthält vollständige C#-Beispiele, die zeigen, wie mehrteilige Anforderungen an die Verwaltungs-APIs von digitalen Zwillingen in Azure gerichtet werden.

Blobmetadaten

Neben Content-Type und Content-Disposition müssen mehrteilige Anforderungen für Azure Digital Twins-Blobs auch den richtigen JSON-Text angeben. Der zu übermittelnde JSON-Text hängt von der Art des ausgeführten HTTP-Anforderungsvorgangs ab.

Nachfolgend finden Sie die vier wichtigsten JSON-Schemas:

JSON-Blobmetadaten entsprechen dem folgenden Modell:

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

attribute	type	Beschreibung
parentId	String	Die übergeordnete Entität, der das Blob zugeordnet werden soll (Räume, Geräte oder Benutzer)
name	String	Ein benutzerfreundlicher Name für das Blob
type	String	Der Blobtyp: type und typeId können nicht verwendet werden.
Typeid	Ganzzahl	Die Blobtyp-ID: type und typeId können nicht verwendet werden.
subtype	String	Der Blobuntertyp: subtype und subtypeId können nicht verwendet werden.
subtypeId	Ganzzahl	Die Untertyp-ID des Blobs: subtype und subtypeId können nicht verwendet werden.
Beschreibung	String	Benutzerdefinierte Beschreibung des Blobs
sharing	String	Gibt an, ob das Blob freigegeben werden kann: Enumeration [`None`, `Tree`, `Global`]

Blobmetadaten werden immer als erster Block mit Content-Type application/json oder als .json-Datei angegeben. Dateidaten werden im zweiten Block als einer der unterstützten MIME-Typen angegeben.

In der Swagger-Dokumentation werden diese Modell-Schemas umfassend beschrieben.

Tipp

Es wird eine Swagger-Vorschau bereitgestellt, um den API-Funktionsumfang zu veranschaulichen. Diese Vorschau finden Sie unter docs.westcentralus.azuresmartspaces.net/management/swagger.

Ihre eigene generierte Dokumentation von Verwaltungs-API-Swagger finden Sie unter:

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

Name	Ersetzen mit
YOUR_INSTANCE_NAME	Den Namen Ihrer Azure Digital Twins-Instanz
YOUR_LOCATION	Die Serverregion, in der Ihre Instanz gehostet wird

Informationen zur Verwendung der Referenzdokumentation finden Sie unter Verwenden von Azure Digital Twins-Swagger.

Antwortdaten der Blobs

Einzeln zurückgegebene Blobs haben folgendes JSON-Schema:

{
  "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	type	Beschreibung
id	String	Der eindeutige Bezeichner für das Blob
name	String	Ein benutzerfreundlicher Name für das Blob
parentId	String	Die übergeordnete Entität, der das Blob zugeordnet werden soll (Räume, Geräte oder Benutzer)
type	String	Der Blobtyp: type und typeId können nicht verwendet werden.
Typeid	Ganzzahl	Die Blobtyp-ID: type und typeId können nicht verwendet werden.
subtype	String	Der Blobuntertyp: subtype und subtypeId können nicht verwendet werden.
subtypeId	Ganzzahl	Die Untertyp-ID des Blobs: subtype und subtypeId können nicht verwendet werden.
sharing	String	Gibt an, ob das Blob freigegeben werden kann: Enumeration [`None`, `Tree`, `Global`]
Beschreibung	String	Benutzerdefinierte Beschreibung des Blobs
contentInfos	Array	Gibt unstrukturierte Metadateninformationen an, einschließlich der Version
fullName	String	Der vollständige Name des Blobs
spacePaths	String	Der Raumpfad

Beispiele für mehrteilige Blobanforderung

In den folgenden Beispielen bezieht sich YOUR_MANAGEMENT_API_URL auf den URI der Digital Twins-APIs:

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

Name	Ersetzen mit
YOUR_INSTANCE_NAME	Den Namen Ihrer Azure Digital Twins-Instanz
YOUR_LOCATION	Die Region, in der Ihre Instanz gehostet wird

Um eine Textdatei als Blob hochzuladen und einem Bereich zuzuordnen, richten Sie eine authentifizierte HTTP POST-Anforderung an:

YOUR_MANAGEMENT_API_URL/spaces/blobs

Verwenden Sie folgenden Text:

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

Wert	Ersetzen mit
USER_DEFINED_BOUNDARY	Name für die Begrenzung mehrteiliger Inhalte

Der folgende Code ist eine .NET-Implementierung des gleichen Blob-Uploads mit der Klasse 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);

Abschließend können cURL-Benutzer auf die gleiche Weise mehrteilige Anforderungen ausführen:

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"

Wert	Ersetzen mit
YOUR_TOKEN	Das gültige OAuth 2.0-Token
YOUR_SPACE_ID	Die ID des Raums, der dem Blob zugeordnet werden soll
PATH_TO_FILE	Der Pfad zur Textdatei

Eine erfolgreiche POST-Anforderung gibt die ID des neuen Blobs zurück.

API-Endpunkte

Die folgenden Abschnitte beschreiben die wichtigsten blobbezogenen API-Endpunkte und ihre Funktionen.

Geräte

Blobs können an Geräte angefügt werden. Die folgende Abbildung zeigt die Swagger-Referenzdokumentation für Ihre Verwaltungs-APIs. Sie gibt gerätebezogene API-Endpunkte für die Blobnutzung sowie ggf. zu übergebende erforderliche Pfadparameter an.

Wenn Sie beispielsweise ein Blob aktualisieren oder erstellen und dann an ein Gerät anfügen möchten, richten Sie eine authentifizierte HTTP PATCH-Anforderung an:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

Parameter	Ersetzen mit
YOUR_BLOB_ID	Die gewünschte Blob-ID

Erfolgreiche Anforderungen geben ein JSON-Objekt zurück, wie weiter oben beschrieben.

Leerzeichen

Blobs können auch an Räume angefügt werden. Die folgende Abbildung enthält alle Raum-API-Endpunkte für die Verarbeitung von Blobs. Aufgelistet sind auch alle Pfadparameter, die ggf. an diese Endpunkte übergeben werden müssen.

Wenn beispielsweise ein an einen Raum angefügtes Blob zurückgegeben werden soll, richten Sie eine authentifizierte HTTP GET-Anforderung an:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

Parameter	Ersetzen mit
YOUR_BLOB_ID	Die gewünschte Blob-ID

Erfolgreiche Anforderungen geben ein JSON-Objekt zurück, wie weiter oben beschrieben.

Eine PATCH-Anforderung an denselben Endpunkt aktualisiert die Metadatenbeschreibungen und erstellt Versionen des Blobs. Die HTTP-Anforderung wird unter Verwendung der PATCH-Methode zusammen mit den erforderlichen Metadaten und mehrteiligen Formulardaten ausgeführt.

Benutzer

Blobs können an Benutzermodelle angefügt werden (z. B. um ein Profilbild zuzuordnen). Die folgende Abbildung zeigt die relevanten Benutzer-API-Endpunkte sowie alle ggf. erforderlichen Pfadparameter (z. B. id):

Wenn Sie beispielsweise ein Blob abrufen möchten, das an einen Benutzer angefügt ist, richten Sie eine authentifizierte HTTP GET-Anforderung mit den erforderlichen Formulardaten an:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

Parameter	Ersetzen mit
YOUR_BLOB_ID	Die gewünschte Blob-ID

Erfolgreiche Anforderungen geben ein JSON-Objekt zurück, wie weiter oben beschrieben.

Häufige Fehler

Ein häufiger Fehler ist die Verwendung falscher Headerinformationen:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
Um diesen Fehler zu beheben, stellen Sie sicher, dass die gesamte Anforderung einen geeigneten Content-Type-Header aufweist:
- multipart/mixed
- multipart/form-data
Vergewissern Sie sich außerdem, dass jeder mehrteilige Block einen geeigneten zugehörigen Content-Type aufweist.
Ein zweiter häufiger Fehler tritt auf, wenn derselben Ressource in Ihrem Raumintelligenzgraph mehrere Blobs zugewiesen werden:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Hinweis

Das message-Attribut variiert abhängig von der Ressource.

An jede Ressource im räumlichen Diagramm kann nur ein Blob (jeweils pro Typ) angefügt werden.

Aktualisieren Sie zum Beheben dieses Fehlers das vorhandene Blob, indem Sie den entsprechenden API HTTP PATCH-Vorgang anwenden. Dadurch werden die vorhandenen Blobdaten durch die gewünschten Daten ersetzt.

Nächste Schritte

Weitere Informationen zur Swagger-Referenzdokumentation von Azure Digital Twins finden Sie unter Verwenden von Azure Digital Twins-Swagger.
Weitere Informationen zum Hochladen von Blobs über Postman finden Sie unter Konfigurieren von Postman.

Freigeben über

Hinzufügen von Blobs zu Objekten in Azure Digital Twins

Hochladen von Blobs – Übersicht

Blobmetadaten

Antwortdaten der Blobs

Beispiele für mehrteilige Blobanforderung

API-Endpunkte

Geräte

Leerzeichen

Benutzer

Häufige Fehler

Nächste Schritte

Zusätzliche Ressourcen