Přidat bloky do objektů ve službě Azure Digital Twins

Důležité

Byla vydána nová verze služby Azure Digital Twins. Vzhledem k rozšířeným funkcím nové služby se původní služba Azure Digital Twins (popsaná v této sadě dokumentace) vyřadila z provozu.

Pokud chcete zobrazit dokumentaci k nové službě, navštivte aktivní dokumentaci ke službě Azure Digital Twins.

Objekty blob jsou nestrukturované reprezentace běžných typů souborů, jako jsou obrázky a protokoly. Objekty blob sledují, jaký druh dat představují, pomocí typu MIME (například "image/jpeg") a metadat (název, popis, typ atd.).

Azure Digital Twins podporuje připojování blobů k zařízením, prostorům a uživatelům. Objekty blob můžou představovat profilový obrázek pro uživatele, fotku zařízení, video, mapu, zip firmwaru, data JSON, protokol atd.

Tento článek předpokládá určitou znalost ověřování v rozhraních API pro správu služby Azure Digital Twins.

Další informace o ověřování pomocí rozhraní API pro správu najdete v tématu Ověřování pomocí rozhraní API služby Azure Digital Twins.
Pokud se chcete ověřit pomocí rozhraní API pro správu pomocí klienta REST nástroje Postman, přečtěte si Postup konfigurace nástroje Postman.

Přehled nahrávání blobů

Vícedílné požadavky můžete použít k nahrání blobů do konkrétních koncových bodů a jejich příslušných funkcionalit.

Poznámka:

Vícedílné požadavky obvykle vyžadují tři části:

Hlavička typu obsahu:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
Content-Disposition:
- form-data; name="metadata"
Obsah souboru, který se má nahrát

Content-Type a Content-Disposition se budou lišit v závislosti na scénáři použití.

Žádosti s více částmi je možné provádět programově (prostřednictvím jazyka C#), prostřednictvím klienta REST nebo nástroje, jako je Postman. Klientské nástroje REST můžou mít různé úrovně podpory složitých požadavků na vícedílné části. Nastavení konfigurace se také může mírně lišit od nástroje po nástroj. Ověřte, který nástroj je nejvhodnější pro vaše potřeby.

Důležité

Žádosti typu "multipart" zasílané do rozhraní API pro správu služby Azure Digital Twins typicky obsahují dvě části:

Metadata objektů blob (například přidružený typ MIME), která jsou deklarována Content-Type a/nebo Content-Disposition
Obsah objektu blob, který obsahuje nestrukturovaný obsah souboru, který se má nahrát

Pro požadavky PATCH se nevyžaduje žádná ze dvou částí. Pro operace POST nebo vytvoření jsou vyžadovány obě položky.

Zdrojový kód Occupancy Quickstart obsahuje kompletní příklady v jazyce C#, které demonstrují, jak provádět vícedílné požadavky na rozhraní API pro správu služby Azure Digital Twins.

Metadata objektů blob

Kromě Content-Type a Content-Dispositionmusí požadavky na BLOB služby Azure Digital Twins určit správný JSON text. Který text JSON, který se má odeslat, závisí na typu prováděné operace požadavku HTTP.

Čtyři hlavní schémata JSON jsou:

Metadata objektů blob JSON odpovídají následujícímu modelu:

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

Vlastnost	Typ	Popis
parentId	Řetězec	Nadřazená entita pro přidružení objektu blob (prostory, zařízení nebo uživatelé)
Jméno	Řetězec	Název objektu blob srozumitelný pro lidi
typ	Řetězec	Typ objektu blob – nelze použít typ a typId
typeId	Integer	ID typu blob – nelze použít typ a typeId
podtyp	Řetězec	Podtyp objektu blob – nelze použít podtyp a podtyp podtypId
podtypId	Integer	ID podtypu pro blob – nelze použít podtyp a podtyp podtypId
popis	Řetězec	Přizpůsobený popis datového objektu blob
sdílení	Řetězec	Zda lze objekt blob sdílet – výčet [`None`, `Tree`, `Global`]

Metadata blobu se vždy zadává jako první blok s typu obsahuapplication/json nebo jako .json soubor. Data souboru se zadají do druhého bloku dat a můžou být libovolného podporovaného typu MIME.

Dokumentace ke Swaggeru popisuje tato schémata modelu podrobně.

Návod

K demonstraci sady funkcí rozhraní API je poskytován náhled Swaggeru. Hostuje se v docs.westcentralus.azuresmartspaces.net/management/swagger.

K vlastní vygenerované dokumentaci k rozhraní API pro správu Swaggeru můžete přistupovat na adrese:

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

Název	Nahradit za
YOUR_INSTANCE_NAME	Název instance služby Azure Digital Twins
VAŠE_MÍSTO	V jaké oblasti serveru je vaše instance hostovaná

Informace o použití referenční dokumentace najdete v tématu Jak používat Swagger.

Data odpovědí objektů blob

Jednotlivé vrácené objekty blob odpovídají následujícímu schématu 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"
  ]
}

Vlastnost	Typ	Popis
id	Řetězec	Jedinečný identifikátor objektu typu blob
Jméno	Řetězec	Název objektu blob srozumitelný pro lidi
parentId	Řetězec	Nadřazená entita pro přidružení objektu blob (prostory, zařízení nebo uživatelé)
typ	Řetězec	Typ objektu blob – nelze použít typ a typId
typeId	Integer	ID typu blob – nelze použít typ a typeId
podtyp	Řetězec	Podtyp objektu blob – nelze použít podtyp a podtyp podtypId
podtypId	Integer	ID podtypu pro blob – nelze použít podtyp a podtyp podtypId
sdílení	Řetězec	Zda lze objekt blob sdílet – výčet [`None`, `Tree`, `Global`]
popis	Řetězec	Přizpůsobený popis datového objektu blob
informace o obsahu	Pole	Určuje nestrukturované informace o metadatech včetně verze.
fullName	Řetězec	Úplný název blobu
vesmírnéCesty	Řetězec	Cesta vesmírem

Příklady vícedílných požadavků na blob

V následujících příkladech YOUR_MANAGEMENT_API_URL odkazuje na identifikátor URI rozhraní API služby Digital Twins:

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

Název	Nahradit za
Jméno_vaší_instance	Název instance služby Azure Digital Twins
VAŠE_MÍSTO	Oblast, ve které je vaše instance hostovaná

Pokud chcete nahrát textový soubor jako objekt blob a přidružit ho k prostoru, proveďte ověřený požadavek HTTP POST na:

YOUR_MANAGEMENT_API_URL/spaces/blobs

S následujícím textem:

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

Hodnota	Nahradit za
UŽIVATELEM_DEFINOVANÁ_HRANICE	Název hranice pro obsah s více částmi

Následující kód je implementace rozhraní .NET stejného nahrání objektu blob pomocí třídy 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);

Nakonec cURL uživatelé můžou žádosti o formulář s více částmi provádět stejným způsobem:

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"

Hodnota	Nahradit za
YOUR_TOKEN	Platný token OAuth 2.0
YOUR_SPACE_ID	ID prostoru pro asociaci se specifickým blobem
CESTA_K_SOUBORU	Cesta k textovému souboru

Při úspěšném POST se vrátí ID nového objektu blob.

Koncové body rozhraní API

Následující části popisují základní koncové body rozhraní API související s objekty blob a jejich funkce.

Zařízení

Objekty blob můžete připojit k zařízením. Následující obrázek ukazuje referenční dokumentaci Swaggeru pro vaše rozhraní API pro správu. Určuje koncové body rozhraní API související se zařízeními, které slouží ke spotřebě blobů, a všechny požadované parametry cesty, které se do nich mají předávat.

Pokud chcete například aktualizovat nebo vytvořit objekt blob a připojit objekt blob k zařízení, proveďte ověřený požadavek HTTP PATCH na následující adresu:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

Parametr	Nahradit za
YOUR_BLOB_ID	Požadované ID bloku

Úspěšné požadavky vrátí objekt JSON, jak je popsáno dříve.

Mezery

Bloby můžete také připojit k prostorům. Následující obrázek uvádí všechny koncové body rozhraní API prostoru zodpovědné za zpracování objektů blob. Vypíše také všechny parametry cesty, které se mají předat do těchto koncových bodů.

Pokud chcete například vrátit blob připojený k prostoru, odešlete ověřený požadavek HTTP GET na:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

Parametr	Nahradit za
YOUR_BLOB_ID	Požadované ID bloku

Úspěšné požadavky vrátí objekt JSON, jak je popsáno dříve.

Požadavek PATCH na stejný koncový bod aktualizuje popisy metadat a vytvoří verze objektu blob. Požadavek HTTP se provádí prostřednictvím metody PATCH spolu s potřebnými metadaty a vícedílnými formulářovými daty.

Uživatelé

Objekty blob můžete připojit k uživatelským modelům (například pro přidružení profilového obrázku). Následující obrázek ukazuje relevantní koncové body uživatelského rozhraní API a všechny požadované parametry cesty, jako jsou id:

Pokud například chcete načíst objekt blob připojený k uživateli, proveďte ověřený požadavek HTTP GET s požadovanými údaji formuláře na:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

Parametr	Nahradit za
YOUR_BLOB_ID	Požadované ID bloku

Úspěšné požadavky vrátí objekt JSON, jak je popsáno dříve.

Běžné chyby

Mezi běžné chyby patří nezadání správných informací v hlavičce:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
Pokud chcete tuto chybu vyřešit, ověřte, že má celkový požadavek odpovídající hlavičku Content-Type:
- multipart/mixed
- multipart/form-data
Ověřte také, že každý vícedílný blok dat má odpovídající Content-Type.
Druhá běžná chyba nastává, když je více blobů přiřazeno ke stejnému prostředku v grafu prostorové inteligence :
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Poznámka:

Atribut zprávy se bude lišit v závislosti na zdroji.

Ke každému prostředku v rámci prostorového grafu může být připojen pouze jeden blob každého druhu.

Pokud chcete tuto chybu vyřešit, aktualizujte existující objekt blob pomocí příslušné operace HTTP PATCH rozhraní API. Tím nahradíte stávající data objektu blob požadovanými daty.

Další kroky

Další informace o referenční dokumentaci pro Swagger pro Azure Digital Twins najdete v tématu Použití služby Azure Digital Twins Swagger.
Pokud chcete nahrát objekty blob prostřednictvím nástroje Postman, přečtěte si Postup konfigurace nástroje Postman.

Last updated on 2020-01-10

Sdílet prostřednictvím

Přidat bloky do objektů ve službě Azure Digital Twins

Přehled nahrávání blobů

Metadata objektů blob

Data odpovědí objektů blob

Příklady vícedílných požadavků na blob

Koncové body rozhraní API

Zařízení

Mezery

Uživatelé

Běžné chyby

Další kroky

Další materiály