Azure Digital Twins의 개체에 Blob 추가

아티클
01/10/2020

Important

Azure Digital Twins 서비스의 새 버전이 릴리스되었습니다. 새 서비스의 확장된 기능에 비추어 원래 Azure Digital Twins 서비스(이 설명서 집합에 설명됨)가 사용 중지되었습니다.

새 서비스에 대한 설명서를 보려면 활성 Azure Digital Twins 설명서를 방문하세요.

Blob은 그림 및 로그와 같은 일반적인 파일 형식의 구조화되지 않은 표현입니다. Blob은 MIME 형식(예: "image/jpeg") 및 메타데이터(이름, 설명, 형식 등)를 사용하여 나타내는 데이터의 종류를 추적합니다.

Azure Digital Twins는 디바이스, 공간 및 사용자에게 Blob 연결을 지원합니다. Blob은 사용자, 디바이스 사진, 비디오, 지도, 펌웨어 zip, JSON 데이터, 로그 등에 대한 프로필 사진을 나타낼 수 있습니다.

이 문서에서는 Azure Digital Twins 관리 API에 대한 인증에 대해 잘 알고 있다고 가정합니다.

관리 API를 사용하여 인증하는 방법에 대한 자세한 내용은 Azure Digital Twins API로 인증을 참조하세요.
Postman REST 클라이언트를 사용하여 관리 API로 인증하려면 Postman을 구성하는 방법을 읽어봅니다.

Blob 업로드 개요

다중 파트 요청을 사용하여 특정 엔드포인트 및 해당 기능에 Blob을 업로드할 수 있습니다.

참고 항목

다중 파트 요청에는 일반적으로 다음 세 가지가 필요합니다.

Content-Type 헤더:
- application/json; charset=utf-8
- multipart/form-data; boundary="USER_DEFINED_BOUNDARY"
콘텐츠 처리:
- form-data; name="metadata"
업로드할 파일 콘텐츠

콘텐츠 형식 및 콘텐츠 처리 는 사용 시나리오에 따라 달라집니다.

다중 파트 요청은 프로그래밍 방식으로(C#을 통해), REST 클라이언트 또는 Postman과 같은 도구를 통해 수행할 수 있습니다. REST 클라이언트 도구는 복잡한 다중 파트 요청에 대한 다양한 수준의 지원을 가질 수 있습니다. 구성 설정은 도구마다 약간씩 다를 수 있습니다. 사용자의 요구에 가장 적합한 도구를 확인합니다.

Important

Azure Digital Twins 관리 API에 대한 다중 파트 요청은 일반적으로 다음과 같은 두 파트로 구성됩니다.

Content-Type 및/또는 Content-Disposition에서 선언한 Blob 메타데이터(예: 연결된 MIME 형식)
업로드할 파일의 구조화되지 않은 콘텐츠가 포함된 Blob 콘텐츠

PATCH 요청에는 두 부분 모두 필요하지 않습니다. 둘 다 POST 또는 만들기 작업에 필요합니다.

점유 빠른 시작 소스 코드에는 Azure Digital Twins 관리 API에 대해 다중 파트 요청을 만드는 방법을 보여주는 전체 C# 예제가 포함되어 있습니다.

Blob 메타데이터

콘텐츠 형식 및 콘텐츠 처리 외에도 Azure Digital Twins Blob 다중 파트 요청은 올바른 JSON 본문을 지정해야 합니다. 제출할 JSON 본문은 수행 중인 HTTP 요청 작업의 종류에 따라 달라집니다.

네 가지 주요 JSON 스키마는 다음과 같습니다.

JSON Blob 메타데이터는 다음 모델을 준수합니다.

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

특성	Type	설명
parentId	문자열	Blob을 연결할 부모 엔터티(공백, 디바이스 또는 사용자)입니다.
이름	문자열	Blob에 대한 사람 친화적인 이름
type	문자열	Blob의 형식 - type 및 typeId를 사용할 수 없음
typeId	정수	Blob 형식 ID - type 및 typeId를 사용할 수 없음
하위	문자열	Blob 하위 유형 - 하위 형식 및 subtypeId를 사용할 수 없습니다.
subtypeId	정수	Blob에 대한 하위 형식 ID - subtype 및 subtypeId를 사용할 수 없음
description	문자열	Blob의 사용자 지정 설명입니다.
공유	문자열	Blob을 공유할 수 있는지 여부 - 열거형 [`None`, `Tree`, `Global`]

Blob 메타데이터는 항상 Content-Type application/json 을 사용하는 첫 번째 청크 또는 파일로 .json 제공됩니다. 파일 데이터는 두 번째 청크로 제공되며 지원되는 모든 MIME 형식일 수 있습니다.

Swagger 설명서에서는 이러한 모델 스키마에 대해 자세히 설명합니다.

팁

API 기능 집합을 보여 주는 Swagger 미리 보기가 제공됩니다. docs.westcentralus.azuresmartspaces.net/management/swagger 호스트됩니다.

다음에서 생성된 고유한 관리 API Swagger 설명서에 액세스할 수 있습니다.

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

속성	Replace with
YOUR_INSTANCE_NAME	Azure Digital Twins 인스턴스의 이름
YOUR_LOCATION	인스턴스를 호스팅하는 서버 지역

Swagger를 사용하는 방법을 읽어 참조 설명서를 사용하는 방법을 알아봅니다.

Blob 응답 데이터

개별적으로 반환된 Blob은 다음 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"
  ]
}

특성	Type	설명
id	문자열	Blob의 고유 식별자입니다.
이름	문자열	Blob에 대한 사람 친화적인 이름
parentId	문자열	Blob을 연결할 부모 엔터티(공백, 디바이스 또는 사용자)입니다.
type	문자열	Blob의 형식 - type 및 typeId를 사용할 수 없음
typeId	정수	Blob 형식 ID - type 및 typeId를 사용할 수 없음
하위	문자열	Blob 하위 유형 - 하위 형식 및 subtypeId를 사용할 수 없습니다.
subtypeId	정수	Blob에 대한 하위 형식 ID - subtype 및 subtypeId를 사용할 수 없음
공유	문자열	Blob을 공유할 수 있는지 여부 - 열거형 [`None`, `Tree`, `Global`]
description	문자열	Blob의 사용자 지정 설명입니다.
contentInfos	배열	버전을 포함하는 구조화되지 않은 메타데이터 정보를 지정합니다.
fullName	문자열	Blob의 전체 이름
spacePaths	문자열	공간 경로

Blob 다중 파트 요청 예제

아래 YOUR_MANAGEMENT_API_URL 예제에서는 Digital Twins API의 URI를 참조합니다.

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

속성	Replace with
YOUR_INSTANCE_NAME	Azure Digital Twins 인스턴스의 이름
YOUR_LOCATION	인스턴스를 호스트하는 지역

텍스트 파일을 Blob으로 업로드하고 공백과 연결하려면 인증된 HTTP POST 요청을 수행합니다.

YOUR_MANAGEMENT_API_URL/spaces/blobs

다음 본문을 사용하여 다음을 수행합니다.

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

값	Replace with
USER_DEFINED_BOUNDARY	다중 파트 콘텐츠 경계 이름

다음 코드는 MultipartFormDataContent 클래스를 사용하여 동일한 Blob 업로드의 .NET 구현입니다.

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

마지막으로 cURL 사용자는 동일한 방식으로 다중 파트 양식 요청을 만들 수 있습니다.

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"

값	Replace with
YOUR_TOKEN	유효한 OAuth 2.0 토큰
YOUR_SPACE_ID	Blob을 연결할 공간의 ID입니다.
PATH_TO_FILE	텍스트 파일의 경로

성공적인 POST는 새 Blob의 ID를 반환합니다.

API 엔드포인트

다음 섹션에서는 핵심 Blob 관련 API 엔드포인트 및 해당 기능에 대해 설명합니다.

장치

디바이스에 Blob을 연결할 수 있습니다. 다음 이미지는 관리 API에 대한 Swagger 참조 설명서를 보여 줍니다. Blob 사용을 위한 디바이스 관련 API 엔드포인트와 해당 엔드포인트에 전달해야 하는 모든 경로 매개 변수를 지정합니다.

예를 들어 Blob을 업데이트하거나 만들고 Blob을 디바이스에 연결하려면 인증된 HTTP PATCH 요청을 수행합니다.

YOUR_MANAGEMENT_API_URL/devices/blobs/YOUR_BLOB_ID

매개 변수	Replace with
YOUR_BLOB_ID	원하는 Blob ID

성공한 요청은 앞에서 설명한 대로 JSON 개체를 반환합니다.

공백

Blob을 공백에 연결할 수도 있습니다. 다음 이미지는 Blob 처리를 담당하는 모든 공간 API 엔드포인트를 나열합니다. 이러한 엔드포인트를 전달할 경로 매개 변수도 나열합니다.

예를 들어 공간에 연결된 Blob을 반환하려면 인증된 HTTP GET 요청을 수행합니다.

YOUR_MANAGEMENT_API_URL/spaces/blobs/YOUR_BLOB_ID

매개 변수	Replace with
YOUR_BLOB_ID	원하는 Blob ID

성공한 요청은 앞에서 설명한 대로 JSON 개체를 반환합니다.

동일한 엔드포인트로의 PATCH 요청은 메타데이터 설명을 업데이트하고 Blob의 버전을 만듭니다. HTTP 요청은 필요한 메타 및 다중 파트 양식 데이터와 함께 PATCH 메서드를 통해 수행됩니다.

사용자

사용자 모델에 Blob을 연결할 수 있습니다(예: 프로필 사진 연결). 다음 이미지는 관련 사용자 API 엔드포인트 및 필요한 경로 매개 변수(예: id)를 보여 줍니다.

예를 들어 사용자에 연결된 Blob을 가져오려면 필요한 양식 데이터를 사용하여 인증된 HTTP GET 요청을 수행합니다.

YOUR_MANAGEMENT_API_URL/users/blobs/YOUR_BLOB_ID

매개 변수	Replace with
YOUR_BLOB_ID	원하는 Blob ID

성공한 요청은 앞에서 설명한 대로 JSON 개체를 반환합니다.

일반 오류

일반 오류는 올바른 헤더 정보를 제공하지 않는 것과 관련됩니다.
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "Invalid media type in first section."
    }
}
```
이 오류를 해결하려면 전체 요청에 적절한 Content-type 헤더가 있는지 확인합니다.
- multipart/mixed
- multipart/form-data
또한 각 다중 파트 청크 에 적절한 해당 Content-Type이 있는지 확인합니다.
두 번째 일반적인 오류는 공간 인텔리전스 그래프에서 여러 Blob이 동일한 리소스에 할당될 때 발생합니다.
```
{
    "error": {
        "code": "400.600.000.000",
        "message": "SpaceBlobMetadata already exists."
    }
}
```
참고 항목

메시지 특성은 리소스에 따라 달라집니다.

각 종류의 Blob 하나만 공간 그래프 내의 각 리소스에 연결될 수 있습니다.

이 오류를 해결하려면 적절한 API HTTP PATCH 작업을 사용하여 기존 Blob을 업데이트합니다. 이렇게 하면 기존 Blob 데이터가 원하는 데이터로 대체됩니다.

다음 단계

Azure Digital Twins에 대한 Swagger 참조 설명서의 자세한 내용은 Azure Digital Twins Swagger 사용을 참조하세요.
Postman을 통해 Blob을 업로드하려면 Postman을 구성하는 방법을 읽어봅니다.

다음을 통해 공유

Azure Digital Twins의 개체에 Blob 추가

Blob 업로드 개요

Blob 메타데이터

Blob 응답 데이터

Blob 다중 파트 요청 예제

API 엔드포인트

장치

공백

사용자

일반 오류

다음 단계

추가 리소스