Azure Digital Twins'de nesnelere blob ekleme

Makale
01/10/2020

Önemli

Azure Digital Twins hizmetinin yeni bir sürümü yayınlandı. Yeni hizmetin genişletilmiş özellikleri ışığında özgün Azure Digital Twins hizmeti (bu belge kümesinde açıklanmıştır) kullanımdan kaldırılmıştır.

Yeni hizmetin belgelerini görüntülemek için etkin Azure Digital Twins Belgeleri'ni ziyaret edin.

Bloblar, resimler ve günlükler gibi yaygın dosya türlerinin yapılandırılmamış gösterimleridir. Bloblar, MIME türü (örneğin: "resim/jpeg") ve meta verileri (ad, açıklama, tür vb.) kullanarak ne tür verileri temsil ettiklerini izler.

Azure Digital Twins cihazlara, alanlara ve kullanıcılara blob eklemeyi destekler. Bloblar bir kullanıcı, cihaz fotoğrafı, video, harita, üretici yazılımı zip'i, JSON verileri, günlük vb. için profil resmini temsil edebilir.

Bu makalede, Azure Digital Twins Yönetim API'lerinizde kimlik doğrulaması hakkında bilgi sahibi olduğunuz varsayılır.

Yönetim API'lerinizle kimlik doğrulaması hakkında daha fazla bilgi edinmek için Azure Digital Twins API'leriyle kimlik doğrulamayı okuyun.
Postman REST istemcisini kullanarak Yönetim API'lerinizle kimlik doğrulaması yapmak için Postman'i yapılandırma makalesini okuyun.

Blobları karşıya yüklemeye genel bakış

Blobları belirli uç noktalara ve ilgili işlevlerine yüklemek için çok parçalı istekleri kullanabilirsiniz.

Not

Çok parçalı istekler genellikle üç parça gerektirir:

content-type üst bilgisi:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
İçerik Bırakma:
- form-data; name="metadata"
Karşıya yüklenecek dosya içeriği

İçerik Türü ve İçerik Bırakma, kullanım senaryosuna bağlı olarak değişir.

Çok parçalı istekler program aracılığıyla (C# aracılığıyla), REST istemcisi veya Postman gibi bir araç aracılığıyla yapılabilir. REST istemci araçlarının karmaşık çok parçalı istekler için farklı destek düzeyleri olabilir. Yapılandırma ayarları da araçtan aracilara göre biraz değişiklik gösterebilir. Hangi aracın ihtiyaçlarınıza en uygun olduğunu doğrulayın.

Önemli

Azure Digital Twins Yönetim API'lerine yapılan çok parçalı isteklerin genellikle iki bölümü vardır:

content-type ve/veya Content-Disposition tarafından bildirilen blob meta verileri (ilişkili MIME türü gibi)
Karşıya yüklenecek dosyanın yapılandırılmamış içeriğini içeren blob içeriği

PATCH istekleri için iki bölümden hiçbiri gerekli değildir. Her ikisi de POST veya oluşturma işlemleri için gereklidir.

Doluluk Hızlı Başlangıç kaynak kodu, Azure Digital Twins Yönetim API'lerine karşı çok parçalı istekler yapmayı gösteren eksiksiz C# örnekleri içerir.

Blob meta verileri

Content-Type ve Content-Disposition'a ek olarak, Azure Digital Twins blob çok parçalı isteklerin doğru JSON gövdesini belirtmesi gerekir. Hangi JSON gövdesinin gönderildiği, gerçekleştirilmekte olan HTTP isteği işleminin türüne bağlıdır.

Dört ana JSON şeması şunlardır:

JSON blob meta verileri aşağıdaki modele uygundur:

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

Öznitelik	Tür	Açıklama
Parentıd	Dize	Blobu ilişkilendirmek için üst varlık (boşluklar, cihazlar veya kullanıcılar)
name	Dize	Blob için insan dostu bir ad
tür	Dize	Blob türü - type ve typeId kullanılamaz
Typeıd	Tamsayı	Blob türü kimliği - type ve typeId kullanamaz
Alt	Dize	Blob alt türü - alt türü ve subtypeId'yi kullanamaz
subtypeId	Tamsayı	Blob için alt tür kimliği - alt türü ve subtypeId'yi kullanamaz
açıklama	Dize	Blobun özelleştirilmiş açıklaması
Paylaşım	Dize	Blob'un paylaşılıp paylaşılamayacağı - sabit listesi [`None`, `Tree`, `Global`]

Blob meta verileri her zaman content-Typeapplication/json içeren ilk öbek veya dosya olarak .json sağlanır. Dosya verileri ikinci öbekte sağlanır ve desteklenen herhangi bir MIME türünde olabilir.

Swagger belgelerinde bu model şemaları tüm ayrıntılarıyla açıklanmaktadır.

İpucu

API özellik kümesini göstermek için bir Swagger sneak önizlemesi sağlanır. docs.westcentralus.azuresmartspaces.net/management/swagger'da barındırlenmektedir.

Kendi oluşturduğunuz Yönetim API'si Swagger belgelerine şu konumdan erişebilirsiniz:

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

Name	Şununla değiştir
YOUR_INSTANCE_NAME	Azure Digital Twins örneğinizin adı
YOUR_LOCATION	Örneğinizin barındırıldığı sunucu bölgesi

Swagger'ı kullanma belgesini okuyarak başvuru belgelerini kullanma hakkında bilgi edinin.

Bloblar yanıt verileri

Tek tek döndürülen bloblar aşağıdaki JSON şemasına uygundur:

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

Öznitelik	Tür	Açıklama
id	Dize	Blob için benzersiz tanımlayıcı
name	Dize	Blob için insan dostu bir ad
Parentıd	Dize	Blobu ilişkilendirmek için üst varlık (boşluklar, cihazlar veya kullanıcılar)
Türü	Dize	Blob türü - type ve typeId kullanılamaz
Typeıd	Tamsayı	Blob türü kimliği - type ve typeId kullanamaz
Alt	Dize	Blob alt türü - alt türü ve subtypeId'yi kullanamaz
subtypeId	Tamsayı	Blob için alt tür kimliği - alt türü ve subtypeId'yi kullanamaz
Paylaşım	Dize	Blob'un paylaşılıp paylaşılamayacağı - sabit listesi [`None`, `Tree`, `Global`]
açıklama	Dize	Blobun özelleştirilmiş açıklaması
contentInfos	Dizi	Sürüm de dahil olmak üzere yapılandırılmamış meta veri bilgilerini belirtir
fullName	Dize	Blobun tam adı
spacePaths	Dize	Boşluk yolu

Blob çok parçalı istek örnekleri

Aşağıdaki örneklerde Digital YOUR_MANAGEMENT_API_URL Twins API'lerinin URI'sine başvurur:

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

Name	Şununla değiştir
YOUR_INSTANCE_NAME	Azure Digital Twins örneğinizin adı
YOUR_LOCATION	Örneğinizin barındırılıyor olduğu bölge

Bir metin dosyasını blob olarak karşıya yüklemek ve bir alanla ilişkilendirmek için, kimliği doğrulanmış bir HTTP POST isteği gönderin:

YOUR_MANAGEMENT_API_URL/spaces/blobs

Aşağıdaki gövde ile:

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

Değer	Şununla değiştir
USER_DEFINED_BOUNDARY	Çok parçalı içerik sınırı adı

Aşağıdaki kod, MultipartFormDataContent sınıfını kullanarak aynı blob karşıya yüklemesinin bir .NET uygulamasıdır:

//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);

Son olarak , cURL kullanıcıları aynı şekilde çok parçalı form istekleri yapabilir:

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"

Değer	Şununla değiştir
YOUR_TOKEN	Geçerli OAuth 2.0 belirteciniz
YOUR_SPACE_ID	Blobu ilişkilendirilecek alanın kimliği
PATH_TO_FILE	Metin dosyanızın yolu

Başarılı bir POST, yeni blobun kimliğini döndürür.

API uç noktaları

Aşağıdaki bölümlerde blobla ilgili temel API uç noktaları ve işlevleri açıklanmaktadır.

Cihazlar

Cihazlara blob ekleyebilirsiniz. Aşağıdaki görüntüde, Yönetim API'leriniz için Swagger başvuru belgeleri gösterilmektedir. Blob tüketimi için cihazla ilgili API uç noktalarını ve bunlara geçirmek için gerekli yol parametrelerini belirtir.

Örneğin, bir blobu güncelleştirmek veya oluşturmak ve blobu bir cihaza eklemek için kimliği doğrulanmış bir HTTP PATCH isteği oluşturun:

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

Parametre	Şununla değiştir
YOUR_BLOB_ID	İstenen blob kimliği

Başarılı istekler daha önce açıklandığı gibi bir JSON nesnesi döndürür.

Boşluklar

Blobları boşluklara da ekleyebilirsiniz. Aşağıdaki görüntüde blobları işlemeden sorumlu tüm alan API'leri uç noktaları listelemektedir. Ayrıca bu uç noktalara geçirmek için tüm yol parametrelerini listeler.

Örneğin, bir alana bağlı bir blobu döndürmek için, kimliği doğrulanmış bir HTTP GET isteği oluşturun:

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

Parametre	Şununla değiştir
YOUR_BLOB_ID	İstenen blob kimliği

Başarılı istekler daha önce açıklandığı gibi bir JSON nesnesi döndürür.

Aynı uç noktaya yönelik PATCH isteği meta veri açıklamalarını güncelleştirir ve blobun sürümlerini oluşturur. HTTP isteği PATCH yöntemiyle, gerekli meta veriler ve çok parçalı form verileriyle birlikte yapılır.

Kullanıcılar

Blobları kullanıcı modellerine ekleyebilirsiniz (örneğin, profil resmini ilişkilendirmek için). Aşağıdaki görüntüde ilgili kullanıcı API'sinin uç noktaları ve gibi idgerekli yol parametreleri gösterilmektedir:

Örneğin, kullanıcıya bağlı bir blobu getirmek için, aşağıdakiler için gerekli form verilerini içeren kimliği doğrulanmış bir HTTP GET isteği oluşturun:

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

Parametre	Şununla değiştir
YOUR_BLOB_ID	İstenen blob kimliği

Başarılı istekler daha önce açıklandığı gibi bir JSON nesnesi döndürür.

Sık karşılaşılan hatalar

Yaygın hatalardan biri, doğru üst bilgi bilgilerinin sağlanmamasıdır:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
Bu hatayı çözmek için, genel isteğin uygun bir İçerik Türü üst bilgisine sahip olduğunu doğrulayın:
- multipart/mixed
- multipart/form-data
Ayrıca, her çok parçalı öbeklerin uygun bir content-Type değerine sahip olduğunu doğrulayın.
Uzamsal zeka grafınızdaki aynı kaynağa birden çok blob atandığında ikinci bir yaygın hata oluşur:
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
Not

İleti özniteliği kaynağa göre değişir.

Uzamsal grafınızdaki her kaynağa yalnızca bir blob (her türden) eklenebilir.

Bu hatayı çözmek için uygun API HTTP PATCH işlemini kullanarak mevcut blobu güncelleştirin. Bunu yaptığınızda mevcut blob verileri istenen verilerle değiştirilir.

Sonraki adımlar

Azure Digital Twins için Swagger başvuru belgeleri hakkında daha fazla bilgi edinmek için Bkz. Azure Digital Twins Swagger'ı kullanma.
Postman aracılığıyla blobları karşıya yüklemek için Postman'i yapılandırma'yı okuyun.

Azure Digital Twins'de nesnelere blob ekleme

Blobları karşıya yüklemeye genel bakış

Blob meta verileri

Bloblar yanıt verileri

Blob çok parçalı istek örnekleri

API uç noktaları

Cihazlar

Boşluklar

Kullanıcılar

Sık karşılaşılan hatalar

Sonraki adımlar

Ek kaynaklar