JavaScript용 Azure Digital Twins Core 클라이언트 라이브러리 - 버전 1.1.0

아티클
04/05/2023

이 패키지에는 트윈, 모델, 관계 등을 관리하기 위한 Azure Digital Twins 서비스에 대한 액세스를 제공하는 Azure Digital Twins API용 등형 SDK가 포함되어 있습니다.

시작

현재 지원되는 환경

Node.js의 LTS 버전
최신 버전의 Safari, Chrome, Edge, Firefox.

자세한 내용은 지원 정책을 참조하세요.

사전 요구 사항

Azure Digital Twins 인스턴스.

`@azure/digital-twins-core` 패키지를 설치합니다.

를 사용하여 JavaScript용 Digital Twins Core 클라이언트 라이브러리를 npm설치합니다.

npm install @azure/digital-twins-core

브라우저 지원

JavaScript 번들

브라우저에서 이 클라이언트 라이브러리를 사용하려면 먼저 번들러를 사용해야 합니다. 이 작업을 수행하는 방법에 대한 자세한 내용은 번들링 설명서를 참조하세요.

CORS

Azure Digital Twins는 현재 CORS(원본 간 리소스 공유) 를 지원하지 않습니다. 따라서 이 라이브러리를 사용하여 브라우저에서 템플릿 서비스를 직접 호출할 수 없습니다. 지침은 이 문서를 참조하세요.

주요 개념

Azure Digital Twins

Azure Digital Twins는 실제 환경의 종합적 모델을 만드는 Azure IoT 서비스입니다. 사람, 공간 및 디바이스 간의 관계와 상호 작용을 모델링하는 공간 인텔리전스 그래프를 만들 수 있습니다. Azure Digital Twins 설명서를 방문하여 Azure Digital Twins에 대해 자세히 알아볼 수 있습니다.

`DigitalTwinsClient`

DigitalTwinsClient 는 이 라이브러리의 사용자가 Azure Digital Twins 인스턴스를 관리하는 데 사용하는 클라이언트 개체입니다.

예

DigitalTwinsClient 만들기

새 DigitalTwinsClient를 만들려면 Azure Digital Twins 인스턴스 및 자격 증명에 대한 엔드포인트가 필요합니다. 여기서는 패키지 @azure/identity의 자격 증명에 를 사용합니다DefaultAzureCredential. 다양한 인증 메커니즘을 지원하고 실행 중인 환경에 따라 적절한 자격 증명 유형을 결정합니다. readme for @azure/identity 사용할 수 있는 다양한 인증 옵션에 대한 자세한 내용은 을 참조하세요.

const { DefaultAzureCredential } = require("@azure/identity");
const { DigitalTwinsClient } = require("@azure/digital-twins-core");

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);

모델 만들기, 나열, 가져오기, 서비스 해제 및 삭제

모델 만들기

모델을 만들기 위해 모델 목록을 에 전달합니다 createModels. 여기서는 하나의 모델만 만듭니다.

const myComponent = {
  "@id": "dtmi:my_component;1",
  "@type": "Interface",
  "@context": "dtmi:dtdl:context;2",
  displayName: "Component1",
  contents: [
    {
      "@type": "Property",
      name: "ComponentProp1",
      schema: "string"
    }
  ]
};

const models = await serviceClient.createModels([myComponent]);

모델 나열

를 사용하여 listModels 모든 모델을 나열합니다.

const models = await serviceClient.listModels();
for await (const model of models) {
  console.log(`Model ID: ${model.id}`);
}

모델 가져오기

모델 ID를 사용하여 getModel 특정 모델을 가져올 수 있습니다.

const model = await serviceClient.getModel("<model ID>");

서비스 해제 모델

모델 ID를 사용하여 decomissionModel 모델을 서비스 해제할 수 있습니다.

await serviceClient.decomissionModel("<model ID>");

모델 삭제

모델 ID를 사용하여 deleteModel 모델을 삭제할 수 있습니다.

await serviceClient.deleteModel("<model ID>");

디지털 트윈 만들기, 가져오기, 쿼리 및 삭제

디지털 트윈 만들기

트윈을 만들려면 디지털 트윈에 대한 ID와 디지털 트윈 개체를 포함하는 JSON 문자열을 제공해야 합니다.

const digitalTwinId = "myTwin";
const newTwin = "<JSON containing the digitalTwin object>";
const createdTwin = await serviceClient.upsertDigitalTwin(digitalTwinId, newTwin);

디지털 쌍 가져오기

디지털 트윈 ID를 사용하여 getDigitalTwin 디지털 트윈을 가져올 수 있습니다.

const digitalTwinId = "myTwin";
const twin = await serviceClient.getDigitalTwin(digitalTwinId);
console.log(`DigitalTwin's etag: ${twin.eTag}`);
console.log(`DigitalTwin: ${twin.body}`);

디지털 트윈 쿼리

Azure Digital Twins 쿼리 언어를 사용하여 Azure Digital Twins 인스턴스에서 디지털 트윈을 쿼리합니다. 다음은 디지털 트윈을 쿼리하는 방법과 결과를 반복하는 방법의 예입니다.

const query = "SELECT * FROM digitaltwins";
const queryResult = serviceClient.queryTwins(query);
for await (const item of queryResult) {
  console.log(`DigitalTwin: ${item}`);
}

디지털 트윈 삭제

디지털 트윈 ID를 사용하여 deleteDigitalTwin 디지털 트윈을 삭제할 수 있습니다.

const digitalTwinId = "myTwin";
await serviceClient.deleteDigitalTwin(digitalTwinId);

디지털 트윈 구성 요소 가져오기 및 업데이트

디지털 트윈 구성 요소 가져오기

디지털 트윈 ID 및 구성 요소의 경로와 함께 을 사용하여 getComponent 디지털 트윈 구성 요소를 가져올 수 있습니다.

const digitalTwinId = "myTwin";
const componentPath = "Component1";
const component = await serviceClient.getComponent(digitalTwinId, componentPath);
console.log(`Component: ${component}`);

디지털 트윈 구성 요소 업데이트

디지털 트윈 구성 요소(즉, 디지털 트윈 내에서 구성 요소 속성 또는 하위 속성을 대체, 제거 또는 추가)를 업데이트하려면 디지털 트윈 ID, 구성 요소 경로 및 속성 op 과 path함께 패치 개체 목록을 제공해야 합니다. 값 op 은 "replace", "remove" 또는 "add"이고 path 값은 업데이트되는 디지털 트윈 구성 요소의 경로입니다. "바꾸기" 및 "추가" 작업의 경우 속성은 value 구성 요소 속성의 원하는 값에 포함되어야 합니다.

const digitalTwinId = "myTwin";
const componentPath = "Component1";
const patch = {
  op: "replace",
  path: "/ComponentProp1",
  value: "value2"
};
const updateComponentResponse = await serviceClient.updateComponent(digitalTwinId, componentPath, [
  patch
]);

디지털 트윈 관계 만들기 및 나열

디지털 트윈 관계 만들기

upsertRelationship 는 디지털 트윈의 ID, 관계 이름(이 경우 "has"), 관계의 ID(이 경우 "BuildingHasFloor") 및 만들 관계를 나타내는 개체와 함께 제공되는 디지털 트윈에 관계를 만듭니다. 관계의 대상을 지정하려면 개체에 "$targetId" 키가 있는 속성이 포함되어야 합니다.

const relationship = {
  $relationshipId: "BuildingHasFloor",
  $sourceId: "BuildingTwin",
  $relationshipName: "has",
  $targetId: "FloorTwin",
  isAccessRestricted: false
};

await serviceClient.upsertRelationship(
  relationship["$sourceId"],
  relationship["$relationshipId"],
  relationship
);

디지털 트윈 관계 나열

디지털 트윈 listRelationships 의 경우 모든 listIncomingRelationships 관계와 들어오는 모든 관계를 각각 나열합니다.

const digitalTwinId = "myTwin";
const relationships = serviceClient.listRelationships(digitalTwinId);
for await (const relationship of relationships) {
  console.log(`Relationship: ${relationship}`);
}

const digitalTwinId = "myTwin";
const incomingRelationships = serviceClient.listIncomingRelationships(digitalTwinId);
for await (const incomingRelationship of incomingRelationships) {
  console.log(`Relationship: ${incomingRelationship}`);
}

이벤트 경로 만들기, 가져오기, 나열 및 삭제

이벤트 경로 만들기

이벤트 경로를 만들려면 이벤트 경로의 ID(이 경우 "myEventRouteId")와 아래 예제와 같이 엔드포인트 및 선택적 필터를 포함하는 이벤트 경로 데이터를 제공합니다. 이벤트 필터링에 대한 자세한 내용은 이 설명서를 참조하세요.

const eventHubEndpointName = "myEventHubEndpointName";
const eventRouteId = "myEventRouteId";
const eventFilter =
  "$eventType = 'DigitalTwinTelemetryMessages' or $eventType = 'DigitalTwinLifecycleNotification'";
await serviceClient.upsertEventRoute(eventRouteId, eventHubEndpointName, eventFilter);

이벤트 경로 가져오기

이벤트 경로 ID를 사용하여 getEventRoute 이벤트 경로를 가져올 수 있습니다.

const eventRouteId = "myEventRouteId";
const eventRoute = serviceClient.getEventRoute(eventRouteId);
console.log(`EventRoute: ${eventRoute}`);

이벤트 경로 나열

를 사용하여 listEventRoutes이벤트 경로를 나열할 수 있습니다.

const eventRoutes = serviceClient.listEventRoutes();
for await (const eventRoute of eventRoutes) {
  console.log(`EventRoute: ${eventRoute}`);
}

이벤트 경로 삭제

이벤트 경로 ID를 사용하여 deleteEventRoute 이벤트 경로를 삭제할 수 있습니다.

const eventRouteId = "myEventRouteId";
await serviceClient.deleteEventRoute(eventRouteId);

디지털 트윈에 대한 원격 분석 메시지 게시

디지털 트윈에 대한 원격 분석 메시지를 게시하려면 메시지에 대한 디지털 트윈 ID, 페이로드 및 고유 ID를 제공해야 합니다.

const digitalTwinId = "<digital twin ID>";
const telemetryPayload = '{"Telemetry1": 5}';
const response = await serviceClient.publishTelemetry(
  digitalTwinId,
  telemetryPayload,
  "<unique message ID>"
);

디지털 트윈의 특정 구성 요소에 대한 원격 분석 메시지를 게시할 수도 있습니다. 디지털 트윈 ID, 페이로드 및 고유 메시지 ID 외에도 대상 구성 요소 경로를 지정해야 합니다.

const digitalTwinId = "<digital twin ID>";
const componentPath = "<component path>";
const telemetryPayload = '{"Telemetry1": 5}';
const response = await serviceClient.publishComponentTelemetry(
  digitalTwinId,
  componentPath,
  telemetryPayload,
  "<unique message ID>"
);

추가 예

추가 예제는 샘플 디렉터리에서 찾을 수 있습니다.

문제 해결

로깅

로깅을 사용하도록 설정하면 실패에 대한 유용한 정보를 파악하는 데 도움이 될 수 있습니다. HTTP 요청 및 응답 로그를 보려면 AZURE_LOG_LEVEL 환경 변수를 info로 설정합니다. 또는 @azure/logger에서 setLogLevel을 호출하여 런타임에 로깅을 사용하도록 설정할 수 있습니다.

const { setlogLevel } = require("@azure/logger");

setLogLevel("info");

로그를 사용하는 방법에 대한 자세한 내용은 @azure/logger package docs를 참조하세요.

다음 단계

클라이언트 라이브러리를 사용하는 방법을 보여 주는 자세한 예제는 샘플 디렉터리를 살펴보세요.
Azure Digital Twins 설명서 살펴보기

참여

이 라이브러리에 기여하려면 기여 가이드 를 참조하여 코드를 빌드하고 테스트하는 방법에 대해 자세히 알아보세요.

Javascript용 Microsoft Azure SDK

다음을 통해 공유