[Digital Twins] Update to new api version 2023-06-30

sdk/digitaltwins/digital-twins-core/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Release History
 
+## 2.1.0-beta.1 (2023-06-01)
+### Features Added
+- Updated service API version to use API version 2023-06-30 by default.
+- Added support for the new import job. You can now use a blob file in your storage account to import multiple models, twins and relationships at once.
+
 ## 2.0.0 (Unreleased)
 
 ### Features Added

sdk/digitaltwins/digital-twins-core/review/digital-twins-core.api.md

@@ -40,26 +40,36 @@ export interface DigitalTwinsAddRelationshipOptionalParams extends coreClient.Op
 }
 
 // @public
-export type DigitalTwinsAddRelationshipResponse = DigitalTwinsAddRelationshipHeaders & Record<string, unknown>;
+export type DigitalTwinsAddRelationshipResponse = DigitalTwinsAddRelationshipHeaders & {
+    [propertyName: string]: any;
+};
 
 // @public
-export type DigitalTwinsAddResponse = DigitalTwinsAddHeaders & Record<string, unknown>;
+export type DigitalTwinsAddResponse = DigitalTwinsAddHeaders & {
+    [propertyName: string]: any;
+};
 
 // @public
 export class DigitalTwinsClient {
     constructor(endpointUrl: string, credential: TokenCredential, options?: DigitalTwinsClientOptions);
+    cancelImportJob(importJobId: string, options?: OperationOptions): Promise<ImportJob>;
     createModels(dtdlModels: Array<Record<string, unknown>>, options?: OperationOptions): Promise<DigitalTwinModelsAddResponse>;
     decomissionModel(modelId: string, options?: OperationOptions): Promise<void>;
     deleteDigitalTwin(digitalTwinId: string, options?: DigitalTwinsDeleteOptionalParams): Promise<void>;
     deleteEventRoute(eventRouteId: string, options?: OperationOptions): Promise<void>;
+    deleteImportJob(importJobId: string, options?: OperationOptions): Promise<void>;
     deleteModel(modelId: string, options?: OperationOptions): Promise<void>;
     deleteRelationship(digitalTwinId: string, relationshipId: string, options?: DigitalTwinsDeleteRelationshipOptionalParams): Promise<void>;
     getComponent(digitalTwinId: string, componentName: string, options?: OperationOptions): Promise<DigitalTwinsGetComponentResponse>;
     getDigitalTwin(digitalTwinId: string, options?: OperationOptions): Promise<DigitalTwinsGetByIdResponse>;
     getEventRoute(eventRouteId: string, options?: OperationOptions): Promise<EventRoutesGetByIdResponse>;
+    // Warning: (ae-forgotten-export) The symbol "ImportJob" needs to be exported by the entry point index.d.ts
+    getImportJob(importJobId: string, options?: OperationOptions): Promise<ImportJob>;
     getModel(modelId: string, options?: GetModelOptions): Promise<DigitalTwinModelsGetByIdResponse>;
     getRelationship(digitalTwinId: string, relationshipId: string, options?: OperationOptions): Promise<DigitalTwinsGetRelationshipByIdResponse>;
     listEventRoutes(options?: ListEventRoutesOptions): PagedAsyncIterableIterator<EventRoute>;
+    // Warning: (ae-forgotten-export) The symbol "ImportJobsListOptionalParams" needs to be exported by the entry point index.d.ts
+    listImportJobs(options?: ImportJobsListOptionalParams): PagedAsyncIterableIterator<ImportJob>;
     listIncomingRelationships(digitalTwinId: string, options?: ListIncomingRelationshipsOptions): PagedAsyncIterableIterator<IncomingRelationship>;
     listModels(options?: ListModelsOptions): PagedAsyncIterableIterator<DigitalTwinsModelData>;
     listRelationships(digitalTwinId: string, options?: ListRelationshipsOptions): PagedAsyncIterableIterator<Record<string, unknown>>;
@@ -71,6 +81,7 @@ export class DigitalTwinsClient {
     updateRelationship(digitalTwinId: string, relationshipId: string, jsonPatch: Array<Record<string, unknown>>, options?: DigitalTwinsUpdateRelationshipOptionalParams): Promise<DigitalTwinsUpdateRelationshipResponse>;
     upsertDigitalTwin(digitalTwinId: string, digitalTwinJson: string, options?: DigitalTwinsAddOptionalParams): Promise<DigitalTwinsAddResponse>;
     upsertEventRoute(eventRouteId: string, endpointId: string, filter: string, options?: OperationOptions): Promise<void>;
+    upsertImportJob(importJobId: string, inputBlobUri: string, outputBlobUri: string, options?: OperationOptions): Promise<ImportJob>;
     upsertRelationship(digitalTwinId: string, relationshipId: string, relationship: Record<string, unknown>, options?: DigitalTwinsAddRelationshipOptionalParams): Promise<DigitalTwinsAddRelationshipResponse>;
 }
 
@@ -94,23 +105,29 @@ export interface DigitalTwinsGetByIdHeaders {
 }
 
 // @public
-export type DigitalTwinsGetByIdResponse = DigitalTwinsGetByIdHeaders & Record<string, unknown>;
+export type DigitalTwinsGetByIdResponse = DigitalTwinsGetByIdHeaders & {
+    [propertyName: string]: any;
+};
 
 // @public
 export interface DigitalTwinsGetComponentHeaders {
     etag?: string;
 }
 
 // @public
-export type DigitalTwinsGetComponentResponse = DigitalTwinsGetComponentHeaders & Record<string, unknown>;
+export type DigitalTwinsGetComponentResponse = DigitalTwinsGetComponentHeaders & {
+    [propertyName: string]: any;
+};
 
 // @public
 export interface DigitalTwinsGetRelationshipByIdHeaders {
     etag?: string;
 }
 
 // @public
-export type DigitalTwinsGetRelationshipByIdResponse = DigitalTwinsGetRelationshipByIdHeaders & Record<string, unknown>;
+export type DigitalTwinsGetRelationshipByIdResponse = DigitalTwinsGetRelationshipByIdHeaders & {
+    [propertyName: string]: any;
+};
 
 // @public
 export type DigitalTwinsListIncomingRelationshipsResponse = IncomingRelationshipCollection;
@@ -181,7 +198,7 @@ export interface EventRoute {
 // @public
 export interface EventRouteCollection {
     nextLink?: string;
-    value?: EventRoute[];
+    value: EventRoute[];
 }
 
 // @public
@@ -207,7 +224,7 @@ export interface IncomingRelationship {
 export interface IncomingRelationshipCollection {
     nextLink?: string;
     // (undocumented)
-    value?: IncomingRelationship[];
+    value: IncomingRelationship[];
 }
 
 // @public
@@ -234,7 +251,7 @@ export interface ListRelationshipsOptions extends coreClient.OperationOptions {
 // @public
 export interface PagedDigitalTwinsModelDataCollection {
     nextLink?: string;
-    value?: DigitalTwinsModelData[];
+    value: DigitalTwinsModelData[];
 }
 
 // @public
@@ -248,7 +265,7 @@ export type QueryQueryTwinsResponse = QueryQueryTwinsHeaders & QueryResult;
 // @public
 export interface QueryResult {
     continuationToken?: string;
-    value?: Record<string, unknown>[];
+    value: Record<string, unknown>[];
 }
 
 // @public
@@ -265,7 +282,7 @@ export interface QueryTwinsOptions extends coreClient.OperationOptions {
 // @public
 export interface RelationshipCollection {
     nextLink?: string;
-    value?: Record<string, unknown>[];
+    value: Record<string, unknown>[];
 }
 
 // (No @packageDocumentation comment for this package)

sdk/digitaltwins/digital-twins-core/samples-dev/dt_import_jobs_get.ts

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * @summary Simple example of how to get an import job.
+ */
+
+import { DefaultAzureCredential } from "@azure/identity";
+import { DigitalTwinsClient } from "@azure/digital-twins-core";
+import { inspect } from "util";
+
+async function main() {
+  // AZURE_DIGITALTWINS_URL: The URL to your Azure Digital Twins instance
+  const url = process.env.AZURE_DIGITALTWINS_URL;
+  if (url === undefined) {
+    throw new Error("Required environment variable AZURE_DIGITALTWINS_URL is not set.");
+  }
+
+  // DefaultAzureCredential is provided by @azure/identity. It supports
+  // different authentication mechanisms and determines the appropriate
+  // credential type based of the environment it is executing in. See
+  // https://www.npmjs.com/package/@azure/identity for more information on
+  // authenticating with DefaultAzureCredential or other implementations of
+  // TokenCredential.
+  const credential = new DefaultAzureCredential();
+  const serviceClient = new DigitalTwinsClient(url, credential);
+
+  // Get event route
+  const importJobId = "<import job ID to get>"; // Import Job ID must exist in your Azure Digital Twins instance
+  const importJob = serviceClient.getImportJob(importJobId);
+  console.log(`EventRoute:`);
+  console.log(inspect(importJob));
+}
+
+main().catch((err) => {
+  console.log("error code: ", err.code);
+  console.log("error message: ", err.message);
+  console.log("error stack: ", err.stack);
+});

sdk/digitaltwins/digital-twins-core/samples-dev/dt_import_jobs_lifecycle.ts

@@ -0,0 +1,76 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * This sample illustrates the lifecycle of an import job using a scenario that shows how to:
+ * - create a DigitalTwins Service Client using the DigitalTwinsClient constructor
+ * - create an import job
+ * - get created import job by importJobId
+ * - list all import jobs by listing them using the paginated API
+ * - cancel the created import job
+ * - delete the created import job
+ * 
+ * @summary demonstrates the lifecycle (create, get, list, decommission, delete) of a model
+ */
+
+import { DefaultAzureCredential } from "@azure/identity";
+import { DigitalTwinsClient } from "@azure/digital-twins-core";
+import { inspect } from "util";
+import { v4 } from "uuid";
+
+// For the purpose of this example we will create temporary model and a temporary component model using random Ids.
+// We have to make sure these model Ids are unique within the DT instance so we use generated UUIDs.
+async function main() {
+  const importJobId = `import-job-${v4()}`;
+  const inputBlobUri = "<input blob uri>"; // Input blob file in a storage container with the correct permissions required;
+  const outputBlobUri = "<output blob uri>"; //Storage container with correct permissions required. If output blob file does not exist, one will be created;
+
+  // AZURE_DIGITALTWINS_URL: The URL to your Azure Digital Twins instance
+  const url = process.env.AZURE_DIGITALTWINS_URL;
+  if (url === undefined) {
+    throw new Error("Required environment variable AZURE_DIGITALTWINS_URL is not set.");
+  }
+
+  // DefaultAzureCredential is provided by @azure/identity. It supports
+  // different authentication mechanisms and determines the appropriate
+  // credential type based of the environment it is executing in. See
+  // https://www.npmjs.com/package/@azure/identity for more information on
+  // authenticating with DefaultAzureCredential or other implementations of
+  // TokenCredential.
+  const credential = new DefaultAzureCredential();
+  const serviceClient = new DigitalTwinsClient(url, credential);
+
+  // Create import job
+  const createdImportJob = await serviceClient.upsertImportJob(importJobId, inputBlobUri, outputBlobUri);
+  console.log(`Created import Job:`);
+  console.log(inspect(createdImportJob));
+
+  // Get created import job
+  const getImportJob = await serviceClient.getImportJob(importJobId);
+  console.log(`Get Import Job:`);
+  console.log(inspect(getImportJob));
+
+  // List all import jobs
+  const listedImportJobs = serviceClient.listImportJobs();
+  console.log(`Import Job list`);
+  for await (const importJob of listedImportJobs) {
+    console.log(`Import Job:`);
+    console.log(inspect(importJob));
+  }
+
+  // Cancel import job
+  let response = await serviceClient.cancelImportJob(importJobId);
+  console.log(`Cancel Import Job response:`);
+  console.log(inspect(response));
+
+  // Delete import job
+  await serviceClient.deleteImportJob(importJobId);
+  console.log(`Delete Model response:`);
+  console.log(inspect(response));
+}
+
+main().catch((err) => {
+  console.log("error code: ", err.code);
+  console.log("error message: ", err.message);
+  console.log("error stack: ", err.stack);
+});

sdk/digitaltwins/digital-twins-core/samples-dev/dt_import_jobs_list.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * @summary Simple example of how to list all import jobs using the paginated API
+ */
+
+import { DefaultAzureCredential } from "@azure/identity";
+import { DigitalTwinsClient } from "@azure/digital-twins-core";
+import { inspect } from "util";
+
+async function main() {
+  // AZURE_DIGITALTWINS_URL: The URL to your Azure Digital Twins instance
+  const url = process.env.AZURE_DIGITALTWINS_URL;
+  if (url === undefined) {
+    throw new Error("Required environment variable AZURE_DIGITALTWINS_URL is not set.");
+  }
+
+  // DefaultAzureCredential is provided by @azure/identity. It supports
+  // different authentication mechanisms and determines the appropriate
+  // credential type based of the environment it is executing in. See
+  // https://www.npmjs.com/package/@azure/identity for more information on
+  // authenticating with DefaultAzureCredential or other implementations of
+  // TokenCredential.
+  const credential = new DefaultAzureCredential();
+  const serviceClient = new DigitalTwinsClient(url, credential);
+
+  // List event routes
+  const importJobs = serviceClient.listImportJobs();
+  for await (const importJob of importJobs) {
+    console.log(`ImportJob:`);
+    console.log(inspect(importJob));
+  }
+}
+
+main().catch((err) => {
+  console.log("error code: ", err.code);
+  console.log("error message: ", err.message);
+  console.log("error stack: ", err.stack);
+});

sdk/digitaltwins/digital-twins-core/samples/v1/javascript/dt_import_jobs_get.js

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * @summary Simple example of how to get an import job.
+ */
+
+import { DefaultAzureCredential } from "@azure/identity";
+import { DigitalTwinsClient } from "@azure/digital-twins-core";
+import { inspect } from "util";
+
+async function main() {
+  // AZURE_DIGITALTWINS_URL: The URL to your Azure Digital Twins instance
+  const url = process.env.AZURE_DIGITALTWINS_URL;
+  if (url === undefined) {
+    throw new Error("Required environment variable AZURE_DIGITALTWINS_URL is not set.");
+  }
+
+  // DefaultAzureCredential is provided by @azure/identity. It supports
+  // different authentication mechanisms and determines the appropriate
+  // credential type based of the environment it is executing in. See
+  // https://www.npmjs.com/package/@azure/identity for more information on
+  // authenticating with DefaultAzureCredential or other implementations of
+  // TokenCredential.
+  const credential = new DefaultAzureCredential();
+  const serviceClient = new DigitalTwinsClient(url, credential);
+
+  // Get event route
+  const importJobId = "<import job ID to get>"; // Import Job ID must exist in your Azure Digital Twins instance
+  const importJob = serviceClient.getImportJob(importJobId);
+  console.log(`EventRoute:`);
+  console.log(inspect(importJob));
+}
+
+main().catch((err) => {
+  console.log("error code: ", err.code);
+  console.log("error message: ", err.message);
+  console.log("error stack: ", err.stack);
+});