Udostępnij za pośrednictwem

Dodawanie obiektów blob do obiektów w usłudze Azure Digital Twins

  • Artykuł

Ważne

Udostępniono nową wersję usługi Azure Digital Twins. W świetle rozszerzonych możliwości nowej usługi oryginalna usługa Azure Digital Twins (opisana w tym zestawie dokumentacji) została wycofana.

Aby wyświetlić dokumentację nowej usługi, odwiedź aktywną dokumentację usługi Azure Digital Twins.

Obiekty blob to nieustrukturyzowane reprezentacje typowych typów plików, takich jak obrazy i dzienniki. Obiekty blob śledzą, jakiego rodzaju dane reprezentują przy użyciu typu MIME (na przykład "image/jpeg") i metadanych (nazwa, opis, typ itd.).

Usługa Azure Digital Twins obsługuje dołączanie obiektów blob do urządzeń, przestrzeni i użytkowników. Obiekty blob mogą reprezentować obraz profilu użytkownika, zdjęcie urządzenia, wideo, mapę, plik zip oprogramowania układowego, dane JSON, dziennik itp.

W tym artykule przyjęto założenie, że znajomość uwierzytelniania w interfejsach API zarządzania usługą Azure Digital Twins.

Omówienie przekazywania obiektów blob

Żądania wieloczęściowe umożliwiają przekazywanie obiektów blob do określonych punktów końcowych i ich odpowiednich funkcji.

Uwaga

Żądania wieloczęściowe zwykle wymagają trzech elementów:

  • Nagłówek Content-Type:
    • application/json; charset=utf-8
    • multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
  • Dyspozycja zawartości:
    • form-data; name="metadata"
  • Zawartość pliku do przekazania

Typ zawartości i dyspozycja zawartości będą się różnić w zależności od scenariusza użycia.

Żądania wieloczęściowe można wykonywać programowo (za pośrednictwem języka C#), za pośrednictwem klienta REST lub narzędzia, takiego jak Postman. Narzędzia klienckie REST mogą mieć różne poziomy obsługi złożonych żądań wieloczęściowych. Ustawienia konfiguracji mogą się również nieznacznie różnić od narzędzia do narzędzia. Sprawdź, które narzędzie najlepiej odpowiada Twoim potrzebom.

Ważne

Żądania wieloczęściowe wysyłane do interfejsów API zarządzania usługą Azure Digital Twins zwykle mają dwie części:

  • Metadane obiektów blob (takie jak skojarzony typ MIME) zadeklarowane przez typ zawartości i/lub content-disposition
  • Zawartość obiektu blob, która zawiera nieustrukturyzowaną zawartość pliku do przekazania

Żadna z dwóch części nie jest wymagana w przypadku żądań PATCH . Oba są wymagane w przypadku operacji POST lub tworzenia.

Kod źródłowy Przewodnika Szybki start zajętości zawiera kompletne przykłady języka C#, które pokazują, jak wykonywać żądania wieloczęściowe względem interfejsów API zarządzania usługą Azure Digital Twins.

Metadane obiektu blob

Oprócz typu zawartości i dyspozycji zawartości żądania wieloczęściowe obiektów blob usługi Azure Digital Twins muszą określać poprawną treść JSON. Treść JSON do przesłania zależy od rodzaju wykonywanej operacji żądania HTTP.

Cztery główne schematy JSON to:

Schematy JSON

Metadane obiektu blob JSON są zgodne z następującym modelem:

{
    "parentId": "00000000-0000-0000-0000-000000000000",
    "name": "My First Blob",
    "type": "Map",
    "subtype": "GenericMap",
    "description": "A well chosen description",
    "sharing": "None"
  }
Atrybut Type Opis
parentId String Jednostka nadrzędna do skojarzenia obiektu blob z (spacjami, urządzeniami lub użytkownikami)
name String Przyjazna dla człowieka nazwa obiektu blob
type String Typ obiektu blob — nie może używać typu i typeId
typeId Integer Identyfikator typu obiektu blob — nie można użyć typu i identyfikatora typeId
Podtypu String Podtyp obiektu blob — nie można użyć podtypu i podtypuId
subtypeId Integer Identyfikator podtypu obiektu blob — nie można użyć podtypu i podtypuId
opis String Dostosowany opis obiektu blob
Udostępnianie String Czy obiekt blob może być współużytkowany — wyliczenie [None, Tree, Global]

Metadane obiektu blob są zawsze dostarczane jako pierwszy fragment z typem application/json zawartości lub plikiem .json . Dane pliku są dostarczane w drugim fragmentie i mogą być dowolnym obsługiwanym typem MIME.

W dokumentacji struktury Swagger szczegółowo opisano te schematy modelu.

Napiwek

Dostępna jest wersja zapoznawcza programu Swagger w celu zademonstrowania zestawu funkcji interfejsu API. Jest on hostowany w docs.westcentralus.azuresmartspaces.net/management/swagger.

Dostęp do własnej dokumentacji wygenerowanego interfejsu API zarządzania programu Swagger można uzyskać pod adresem:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/swagger
Nazwisko Replace with
YOUR_INSTANCE_NAME Nazwa wystąpienia usługi Azure Digital Twins
YOUR_LOCATION Region serwera, w którym jest hostowane używane wystąpienie

Dowiedz się więcej na temat korzystania z dokumentacji referencyjnej, czytając artykuł How to use Swagger (Jak używać struktury Swagger).

Dane odpowiedzi obiektów blob

Indywidualnie zwracane obiekty blob są zgodne z następującym schematem JSON:

{
  "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"
  ]
}
Atrybut Type Opis
id String Unikatowy identyfikator obiektu blob
name String Przyjazna dla człowieka nazwa obiektu blob
parentId String Jednostka nadrzędna do skojarzenia obiektu blob z (spacjami, urządzeniami lub użytkownikami)
type String Typ obiektu blob — nie może używać typu i typeId
typeId Integer Identyfikator typu obiektu blob — nie można użyć typu i identyfikatora typeId
Podtypu String Podtyp obiektu blob — nie można użyć podtypu i podtypuId
subtypeId Integer Identyfikator podtypu obiektu blob — nie można użyć podtypu i podtypuId
Udostępnianie String Czy obiekt blob może być współużytkowany — wyliczenie [None, Tree, Global]
opis String Dostosowany opis obiektu blob
contentInfos Tablica Określa informacje o metadanych bez struktury, w tym informacje o wersji
fullName String Pełna nazwa obiektu blob
spacePaths String Ścieżka spacji

Metadane obiektu blob są zawsze dostarczane jako pierwszy fragment z typem application/json zawartości lub plikiem .json . Dane pliku są dostarczane w drugim fragmentie i mogą być dowolnym obsługiwanym typem MIME.

Przykłady żądań wieloczęściowych obiektów blob

W poniższych YOUR_MANAGEMENT_API_URL przykładach odwołuje się do identyfikatora URI interfejsów API usługi Digital Twins:

https://YOUR_INSTANCE_NAME.YOUR_LOCATION.azuresmartspaces.net/management/api/v1.0
Nazwisko Replace with
YOUR_INSTANCE_NAME Nazwa wystąpienia usługi Azure Digital Twins
YOUR_LOCATION Region, w którym jest hostowane twoje wystąpienie

Aby przekazać plik tekstowy jako obiekt blob i skojarzyć go z spacją, wykonaj uwierzytelnione żądanie HTTP POST do:

YOUR_MANAGEMENT_API_URL/spaces/blobs

Z następującą treścią:

--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--
Wartość Replace with
USER_DEFINED_BOUNDARY Nazwa granicy zawartości wieloczęściowej

Poniższy kod to implementacja platformy .NET tego samego przekazywania obiektów blob przy użyciu klasy 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);

Ponadto użytkownicy biblioteki cURL mogą wysyłać żądania formularzy wieloczęściowych w ten sam sposób:

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"
Wartość Replace with
YOUR_TOKEN Prawidłowy token protokołu OAuth 2.0
YOUR_SPACE_ID Identyfikator miejsca do skojarzenia obiektu blob z
PATH_TO_FILE Ścieżka do pliku tekstowego

Przykład biblioteki cURL

Pomyślny post zwraca identyfikator nowego obiektu blob.

Punkty końcowe interfejsu API

W poniższych sekcjach opisano podstawowe punkty końcowe interfejsu API związane z obiektami blob i ich funkcje.

Urządzenia

Obiekty blob można dołączać do urządzeń. Na poniższej ilustracji przedstawiono dokumentację referencyjną struktury Swagger dla interfejsów API zarządzania. Określa on punkty końcowe interfejsu API związane z urządzeniem dla użycia obiektów blob i wszystkie wymagane parametry ścieżki, które mają być do nich przekazywane.

Obiekty blob urządzeń

Na przykład aby zaktualizować lub utworzyć obiekt blob i dołączyć obiekt blob do urządzenia, wykonaj uwierzytelnione żądanie HTTP PATCH do:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID
Parametr Replace with
YOUR_BLOB_ID Żądany identyfikator obiektu blob

Żądania zakończone powodzeniem zwracają obiekt JSON zgodnie z wcześniejszym opisem.

spacje,

Można również dołączać obiekty blob do spacji. Na poniższej ilustracji wymieniono wszystkie punkty końcowe interfejsu API przestrzeni odpowiedzialne za obsługę obiektów blob. Zawiera również listę wszystkich parametrów ścieżki, które mają być przekazywane do tych punktów końcowych.

Spacje obiektów blob

Aby na przykład zwrócić obiekt blob dołączony do miejsca, wykonaj uwierzytelnione żądanie HTTP GET do:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID
Parametr Replace with
YOUR_BLOB_ID Żądany identyfikator obiektu blob

Żądania zakończone powodzeniem zwracają obiekt JSON zgodnie z wcześniejszym opisem.

Żądanie PATCH do tego samego punktu końcowego aktualizuje opisy metadanych i tworzy wersje obiektu blob. Żądanie HTTP jest wykonywane za pośrednictwem metody PATCH wraz z dowolnymi wymaganymi metadanymi i danymi formularzy wieloczęściowych.

Użytkownicy

Obiekty blob można dołączać do modeli użytkowników (na przykład w celu skojarzenia obrazu profilu). Na poniższej ilustracji przedstawiono odpowiednie punkty końcowe interfejsu API użytkownika i wszystkie wymagane parametry ścieżki, takie jak id:

Obiekty blob użytkownika

Aby na przykład pobrać obiekt blob dołączony do użytkownika, wykonaj uwierzytelnione żądanie HTTP GET z dowolnymi wymaganymi danymi formularza do:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID
Parametr Replace with
YOUR_BLOB_ID Żądany identyfikator obiektu blob

Żądania zakończone powodzeniem zwracają obiekt JSON zgodnie z wcześniejszym opisem.

Typowe błędy

  • Typowy błąd polega na braku podawania poprawnych informacji nagłówka:

    {
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}

    Aby rozwiązać ten błąd, sprawdź, czy ogólne żądanie ma odpowiedni nagłówek Content-Type :

    • multipart/mixed
    • multipart/form-data

    Sprawdź również, czy każdy fragment wieloczęściowy ma odpowiedni typ zawartości.

  • Drugi typowy błąd występuje, gdy wiele obiektów blob jest przypisanych do tego samego zasobu na wykresie analizy przestrzennej:

    {
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}

    Uwaga

    Atrybut komunikatu będzie się różnić w zależności od zasobu.

    Do każdego zasobu w grafie przestrzennym może być dołączony tylko jeden obiekt blob (każdego rodzaju).

    Aby rozwiązać ten błąd, zaktualizuj istniejący obiekt blob przy użyciu odpowiedniej operacji HTTP PATCH interfejsu API. Spowoduje to zastąpienie istniejących danych obiektów blob żądanymi danymi.

Następne kroki