Share via


DigitalTwinsClient class

Client for Azure IoT DigitalTwins API.

Constructors

DigitalTwinsClient(string, TokenCredential, DigitalTwinsClientOptions)

Creates an instance of AzureDigitalTwinsAPI.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

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

Methods

createModels(Record<string, unknown>[], OperationOptions)

Create one or many

decomissionModel(string, OperationOptions)

Decommission a model using a json patch. When a model is decommissioned, new digital twins will no longer be able to be defined by this model. However, existing digital twins may continue to use this model. Once a model is decommissioned, it may not be recommissioned.

deleteDigitalTwin(string, DigitalTwinsDeleteOptionalParams)

Delete a digital twin

deleteEventRoute(string, OperationOptions)

Delete an event route.

deleteModel(string, OperationOptions)

Delete a model.

deleteRelationship(string, string, DigitalTwinsDeleteRelationshipOptionalParams)

Delete a relationship on a digital twin.

getComponent(string, string, OperationOptions)

Get a component on a digital twin.

getDigitalTwin(string, OperationOptions)

Get a digital twin

getEventRoute(string, OperationOptions)

Get an event route.

getModel(string, DigitalTwinModelsGetByIdOptionalParams)

Get a model, including the model metadata and the model definition.

getRelationship(string, string, OperationOptions)

Get a relationship on a digital twin.

listEventRoutes(EventRoutesListOptionalParams)

List the event routes in a digital twins instance.

listIncomingRelationships(string, DigitalTwinsListIncomingRelationshipsOptionalParams)

Retrieve all incoming relationships for a digital twin.

listModels(DigitalTwinModelsListOptionalParams)

Get the list of models

listRelationships(string, DigitalTwinsListRelationshipsOptionalParams)

Retrieve relationships for a digital twin.

publishComponentTelemetry(string, string, Record<string, unknown>, string, OperationOptions)

Publish telemetry from a digital twin's component, which is then consumed by one or many destination endpoints (subscribers) defined under.

publishTelemetry(string, Record<string, unknown>, string, OperationOptions)

Publish telemetry from a digital twin, which is then consumed by one or many destination endpoints (subscribers) defined under.

queryTwins(string, QueryQueryTwinsOptionalParams)

Query for digital twins.

updateComponent(string, string, Record<string, unknown>[], DigitalTwinsUpdateComponentOptionalParams)

Update properties of a component on a digital twin using a JSON patch.

updateDigitalTwin(string, Record<string, unknown>[], DigitalTwinsUpdateOptionalParams)

Update a digital twin using a json patch.

updateRelationship(string, string, Record<string, unknown>[], DigitalTwinsUpdateRelationshipOptionalParams)

Updates the properties of a relationship on a digital twin using a JSON patch.

upsertDigitalTwin(string, string, DigitalTwinsAddOptionalParams)

Create or update a digital twin

upsertEventRoute(string, string, string, OperationOptions)

Create or update an event route.

upsertRelationship(string, string, Record<string, unknown>, DigitalTwinsAddRelationshipOptionalParams)

Create or update a relationship on a digital twin.

Constructor Details

DigitalTwinsClient(string, TokenCredential, DigitalTwinsClientOptions)

Creates an instance of AzureDigitalTwinsAPI.

Example usage:

import { DefaultAzureCredential } from "@azure/identity";
import { DigitalTwinsClient } from "@azure/digital-twins-core";

const url = "<URL to Azure Digital Twins instance>";
const credential = new DefaultAzureCredential();
const serviceClient = new DigitalTwinsClient(url, credential);
new DigitalTwinsClient(endpointUrl: string, credential: TokenCredential, options?: DigitalTwinsClientOptions)

Parameters

endpointUrl

string

The endpoint URL of the service.

credential
TokenCredential

Used to authenticate requests to the service.

options
DigitalTwinsClientOptions

Used to configure the service client.

Method Details

createModels(Record<string, unknown>[], OperationOptions)

Create one or many

function createModels(dtdlModels: Record<string, unknown>[], options?: OperationOptions): Promise<DigitalTwinModelsAddResponse>

Parameters

dtdlModels

Record<string, unknown>[]

The set of models to create. Each string corresponds to exactly one model.

options
OperationOptions

The operation options

Returns

The created application/json models.

decomissionModel(string, OperationOptions)

Decommission a model using a json patch. When a model is decommissioned, new digital twins will no longer be able to be defined by this model. However, existing digital twins may continue to use this model. Once a model is decommissioned, it may not be recommissioned.

function decomissionModel(modelId: string, options?: OperationOptions): Promise<void>

Parameters

modelId

string

The Id of the model to decommission. property can be replaced.

options
OperationOptions

The operation options

Returns

Promise<void>

deleteDigitalTwin(string, DigitalTwinsDeleteOptionalParams)

Delete a digital twin

function deleteDigitalTwin(digitalTwinId: string, options?: DigitalTwinsDeleteOptionalParams): Promise<void>

Parameters

digitalTwinId

string

The Id of the digital twin to delete.

options
DigitalTwinsDeleteOptionalParams

Extended operation options including ifMatch: Only perform the operation if the entity's etag matches one of the etags provided or * is provided.

Returns

Promise<void>

deleteEventRoute(string, OperationOptions)

Delete an event route.

function deleteEventRoute(eventRouteId: string, options?: OperationOptions): Promise<void>

Parameters

eventRouteId

string

The Id of the eventRoute to delete.

options
OperationOptions

The operation options

Returns

Promise<void>

deleteModel(string, OperationOptions)

Delete a model.

function deleteModel(modelId: string, options?: OperationOptions): Promise<void>

Parameters

modelId

string

The Id of the model to delete.

options
OperationOptions

The operation options

Returns

Promise<void>

deleteRelationship(string, string, DigitalTwinsDeleteRelationshipOptionalParams)

Delete a relationship on a digital twin.

function deleteRelationship(digitalTwinId: string, relationshipId: string, options?: DigitalTwinsDeleteRelationshipOptionalParams): Promise<void>

Parameters

digitalTwinId

string

The Id of the source digital twin.

relationshipId

string

The Id of the relationship to delete.

options
DigitalTwinsDeleteRelationshipOptionalParams

The operation options ifMatch: Only perform the operation if the entity's etag matches one of the etags provided or * is

Returns

Promise<void>

getComponent(string, string, OperationOptions)

Get a component on a digital twin.

function getComponent(digitalTwinId: string, componentName: string, options?: OperationOptions): Promise<DigitalTwinsGetComponentResponse>

Parameters

digitalTwinId

string

The Id of the digital twin.

componentName

string

The component being retrieved.

options
OperationOptions

The operation options

Returns

Json string representation of the component corresponding to the provided componentName.

getDigitalTwin(string, OperationOptions)

Get a digital twin

function getDigitalTwin(digitalTwinId: string, options?: OperationOptions): Promise<DigitalTwinsGetByIdResponse>

Parameters

digitalTwinId

string

The Id of the digital twin.

options
OperationOptions

The operation options

Returns

The application/json digital twin.

getEventRoute(string, OperationOptions)

Get an event route.

function getEventRoute(eventRouteId: string, options?: OperationOptions): Promise<EventRoute>

Parameters

eventRouteId

string

options
OperationOptions

The operation options

Returns

Promise<EventRoute>

The application/json event route.

getModel(string, DigitalTwinModelsGetByIdOptionalParams)

Get a model, including the model metadata and the model definition.

function getModel(modelId: string, options?: DigitalTwinModelsGetByIdOptionalParams): Promise<DigitalTwinsModelData>

Parameters

modelId

string

The Id of the model.

options
GetModelOptions

Options for this operation

Returns

The application/json model.

getRelationship(string, string, OperationOptions)

Get a relationship on a digital twin.

function getRelationship(digitalTwinId: string, relationshipId: string, options?: OperationOptions): Promise<DigitalTwinsGetRelationshipByIdResponse>

Parameters

digitalTwinId

string

The Id of the source digital twin.

relationshipId

string

The Id of the relationship to retrieve.

options
OperationOptions

The operation options

Returns

The pageable list of application/json relationships belonging to the specified digital twin.

listEventRoutes(EventRoutesListOptionalParams)

List the event routes in a digital twins instance.

function listEventRoutes(options?: EventRoutesListOptionalParams): PagedAsyncIterableIterator<EventRoute, EventRoute[], PageSettings>

Parameters

options
ListEventRoutesOptions

Options for listEventRoutes.

Returns

The application/json event route.

listIncomingRelationships(string, DigitalTwinsListIncomingRelationshipsOptionalParams)

Retrieve all incoming relationships for a digital twin.

function listIncomingRelationships(digitalTwinId: string, options?: DigitalTwinsListIncomingRelationshipsOptionalParams): PagedAsyncIterableIterator<IncomingRelationship, IncomingRelationship[], PageSettings>

Parameters

digitalTwinId

string

The Id of the digital twin.

Returns

listModels(DigitalTwinModelsListOptionalParams)

Get the list of models

function listModels(options?: DigitalTwinModelsListOptionalParams): PagedAsyncIterableIterator<DigitalTwinsModelData, DigitalTwinsModelData[], PageSettings>

Parameters

options
ListModelsOptions

Options for listing models.

Returns

A pageable set of application/json models.

listRelationships(string, DigitalTwinsListRelationshipsOptionalParams)

Retrieve relationships for a digital twin.

function listRelationships(digitalTwinId: string, options?: DigitalTwinsListRelationshipsOptionalParams): PagedAsyncIterableIterator<Record<string, unknown>, Record<string, unknown>[], PageSettings>

Parameters

digitalTwinId

string

The Id of the digital twin.

Returns

PagedAsyncIterableIterator<Record<string, unknown>, Record<string, unknown>[], PageSettings>

publishComponentTelemetry(string, string, Record<string, unknown>, string, OperationOptions)

Publish telemetry from a digital twin's component, which is then consumed by one or many destination endpoints (subscribers) defined under.

function publishComponentTelemetry(digitalTwinId: string, componentName: string, payload: Record<string, unknown>, messageId: string, options?: OperationOptions): Promise<void>

Parameters

digitalTwinId

string

The Id of the digital twin to delete.

componentName

string

The name of the DTDL component.

payload

Record<string, unknown>

The application/json telemetry payload to be sent.

messageId

string

The message Id.

options
OperationOptions

The operation options

Returns

Promise<void>

publishTelemetry(string, Record<string, unknown>, string, OperationOptions)

Publish telemetry from a digital twin, which is then consumed by one or many destination endpoints (subscribers) defined under.

function publishTelemetry(digitalTwinId: string, payload: Record<string, unknown>, messageId: string, options?: OperationOptions): Promise<void>

Parameters

digitalTwinId

string

The Id of the digital twin to delete.

payload

Record<string, unknown>

The application/json telemetry payload to be sent.

messageId

string

The message Id.

options
OperationOptions

The operation options

Returns

Promise<void>

queryTwins(string, QueryQueryTwinsOptionalParams)

Query for digital twins.

function queryTwins(query: string, options?: QueryQueryTwinsOptionalParams): PagedAsyncIterableIterator<Record<string, unknown>, QueryQueryTwinsResponse, PageSettings>

Parameters

query

string

The query string, in SQL-like syntax.

options
QueryTwinsOptions

Options for the query operation.

Returns

The pageable list of query results.

updateComponent(string, string, Record<string, unknown>[], DigitalTwinsUpdateComponentOptionalParams)

Update properties of a component on a digital twin using a JSON patch.

function updateComponent(digitalTwinId: string, componentName: string, jsonPatch: Record<string, unknown>[], options?: DigitalTwinsUpdateComponentOptionalParams): Promise<DigitalTwinsUpdateComponentHeaders>

Parameters

digitalTwinId

string

The Id of the digital twin.

componentName

string

The component being updated.

jsonPatch

Record<string, unknown>[]

The application/json-patch+json operations to be performed on the specified digital twin's component.

options
DigitalTwinsUpdateComponentOptionalParams

Extended operation options including ifMatch: Only perform the operation if the entity's etag matches one of the etags provided or * is provided.

Returns

updateDigitalTwin(string, Record<string, unknown>[], DigitalTwinsUpdateOptionalParams)

Update a digital twin using a json patch.

function updateDigitalTwin(digitalTwinId: string, jsonPatch: Record<string, unknown>[], options?: DigitalTwinsUpdateOptionalParams): Promise<DigitalTwinsUpdateHeaders>

Parameters

digitalTwinId

string

The Id of the digital twin.

jsonPatch

Record<string, unknown>[]

An update specification described by JSON Patch. Updates to property values and $model elements may happen in the same request. Operations are limited to add, replace and remove.

options
DigitalTwinsUpdateOptionalParams

Extended operation options including ifMatch: Only perform the operation if the entity's etag matches one of the etags provided or * is provided.

Returns

updateRelationship(string, string, Record<string, unknown>[], DigitalTwinsUpdateRelationshipOptionalParams)

Updates the properties of a relationship on a digital twin using a JSON patch.

function updateRelationship(digitalTwinId: string, relationshipId: string, jsonPatch: Record<string, unknown>[], options?: DigitalTwinsUpdateRelationshipOptionalParams): Promise<DigitalTwinsUpdateRelationshipHeaders>

Parameters

digitalTwinId

string

The Id of the digital twin to delete.

relationshipId

string

The Id of the relationship to be updated.

jsonPatch

Record<string, unknown>[]

The application/json-patch+json operations to be performed on the specified digital twin's relationship.

options
DigitalTwinsUpdateRelationshipOptionalParams

Extended operation options ifMatch: Only perform the operation if the entity's etag matches one of the etags provided or * is provided.

Returns

upsertDigitalTwin(string, string, DigitalTwinsAddOptionalParams)

Create or update a digital twin

function upsertDigitalTwin(digitalTwinId: string, digitalTwinJson: string, options?: DigitalTwinsAddOptionalParams): Promise<DigitalTwinsAddResponse>

Parameters

digitalTwinId

string

The Id of the digital twin to create or update.

digitalTwinJson

string

The application/json digital twin to create.

options
DigitalTwinsAddOptionalParams

Extended operation options including ifNoneMatch: Only perform the operation if the entity does not already exist.

Returns

The created application/json digital twin.

upsertEventRoute(string, string, string, OperationOptions)

Create or update an event route.

function upsertEventRoute(eventRouteId: string, endpointId: string, filter: string, options?: OperationOptions): Promise<void>

Parameters

eventRouteId

string

The Id of the event route to create or update.

endpointId

string

The id of the endpoint this event route is bound to.

filter

string

An expression which describes the events which are routed to the endpoint.

options
OperationOptions

The operation options

Returns

Promise<void>

upsertRelationship(string, string, Record<string, unknown>, DigitalTwinsAddRelationshipOptionalParams)

Create or update a relationship on a digital twin.

function upsertRelationship(digitalTwinId: string, relationshipId: string, relationship: Record<string, unknown>, options?: DigitalTwinsAddRelationshipOptionalParams): Promise<DigitalTwinsAddRelationshipResponse>

Parameters

digitalTwinId

string

The Id of the source digital twin.

relationshipId

string

The Id of the relationship to create.

relationship

Record<string, unknown>

The application/json relationship to be created.

options
DigitalTwinsAddRelationshipOptionalParams

Extended operation options including ifNoneMatch: Only perform the operation if the entity does not already exist.

Returns