Feat(client): Add Telemetry APIs

sdk/digitaltwins/azure-digitaltwins-core/src/main/java/com/azure/digitaltwins/core/DigitalTwinsAsyncClient.java

@@ -1338,4 +1338,112 @@ Mono<PagedResponse<EventRoute>> listEventRoutesNextPage(String nextLink, Context
     }
 
     //endregion Event Route APIs
+
+    //region Telemetry APIs
+
+    /**
+     * Publishes telemetry from a digital twin
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param payload The application/json telemetry payload to be sent.
+     * @return An empty mono.
+     */
+    public Mono<Void> publishTelemetry(String digitalTwinId, String payload) {
+        TelemetryOptions telemetryOptions = new TelemetryOptions();
+        return withContext(context -> publishTelemetryWithResponse(digitalTwinId, payload, telemetryOptions, context))
+            .flatMap(voidResponse -> Mono.empty());
+    }
+
+    /**
+     * Publishes telemetry from a digital twin
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     * @return An empty mono.
+     */
+    public Mono<Void> publishTelemetry(String digitalTwinId, String payload, TelemetryOptions telemetryOptions) {
+        return withContext(context -> publishTelemetryWithResponse(digitalTwinId, payload, telemetryOptions, context))
+            .flatMap(voidResponse -> Mono.empty());
+    }
+
+    /**
+     * Publishes telemetry from a digital twin
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     * @return A {@link Response} containing an empty mono.
+     */
+    public Mono<Response<Void>> publishTelemetryWithResponse(String digitalTwinId, String payload, TelemetryOptions telemetryOptions) {
+        return withContext(context -> publishTelemetryWithResponse(digitalTwinId, payload, telemetryOptions, context));
+    }
+
+    Mono<Response<Void>> publishTelemetryWithResponse(String digitalTwinId, String payload, TelemetryOptions telemetryOptions, Context context) {
+        return protocolLayer.getDigitalTwins().sendTelemetryWithResponseAsync(
+            digitalTwinId,
+            telemetryOptions.getMessageId(),
+            payload,
+            telemetryOptions.getTimeStamp().toString(),
+            context);
+    }
+
+    /**
+     * Publishes telemetry from a digital twin's component
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param componentName The name of the DTDL component.
+     * @param payload The application/json telemetry payload to be sent.
+     * @return An empty mono.
+     */
+    public Mono<Void> publishComponentTelemetry(String digitalTwinId, String componentName, String payload) {
+        TelemetryOptions telemetryOptions = new TelemetryOptions();
+        return withContext(context -> publishComponentTelemetryWithResponse(digitalTwinId, componentName, payload, telemetryOptions, context))
+            .flatMap(voidResponse -> Mono.empty());
+    }
+
+    /**
+     * Publishes telemetry from a digital twin's component
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param componentName The name of the DTDL component.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     * @return An empty mono.
+     */
+    public Mono<Void> publishComponentTelemetry(String digitalTwinId, String componentName, String payload, TelemetryOptions telemetryOptions) {
+        return withContext(context -> publishComponentTelemetryWithResponse(digitalTwinId, componentName, payload, telemetryOptions, context))
+            .flatMap(voidResponse -> Mono.empty());
+    }
+
+    /**
+     * Publishes telemetry from a digital twin's component
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param componentName The name of the DTDL component.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     * @return A {@link Response} containing an empty mono.
+     */
+    public Mono<Response<Void>> publishComponentTelemetryWithResponse(String digitalTwinId, String componentName, String payload, TelemetryOptions telemetryOptions) {
+        return withContext(context -> publishComponentTelemetryWithResponse(digitalTwinId, componentName, payload, telemetryOptions, context));
+    }
+
+    Mono<Response<Void>> publishComponentTelemetryWithResponse(String digitalTwinId, String componentName, String payload, TelemetryOptions telemetryOptions, Context context) {
+        return protocolLayer.getDigitalTwins().sendComponentTelemetryWithResponseAsync(
+            digitalTwinId,
+            componentName,
+            telemetryOptions.getMessageId(),
+            payload,
+            telemetryOptions.getTimeStamp().toString(),
+            context);
+    }
+
+    //endregion Telemetry APIs
 }

sdk/digitaltwins/azure-digitaltwins-core/src/main/java/com/azure/digitaltwins/core/DigitalTwinsClient.java

@@ -768,4 +768,87 @@ public PagedIterable<EventRoute> listEventRoutes(EventRoutesListOptions options,
     }
 
     //endregion Event Route APIs
+
+    //region Telemetry APIs
+
+    /**
+     * Publishes telemetry from a digital twin
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param payload The application/json telemetry payload to be sent.
+     */
+    public void publishTelemetry(String digitalTwinId, String payload) {
+        TelemetryOptions telemetryOptions = new TelemetryOptions();
+        publishTelemetry(digitalTwinId, payload, telemetryOptions);
+    }
+
+    /**
+     * Publishes telemetry from a digital twin
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     */
+    public void publishTelemetry(String digitalTwinId, String payload, TelemetryOptions telemetryOptions) {
+        publishTelemetryWithResponse(digitalTwinId, payload, telemetryOptions, Context.NONE);
+    }
+
+    /**
+     * Publishes telemetry from a digital twin
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return A {@link Response}.
+     */
+    public Response<Void> publishTelemetryWithResponse(String digitalTwinId, String payload, TelemetryOptions telemetryOptions, Context context) {
+        return digitalTwinsAsyncClient.publishTelemetryWithResponse(digitalTwinId, payload, telemetryOptions, context).block();
+    }
+
+    /**
+     * Publishes telemetry from a digital twin's component
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param componentName The name of the DTDL component.
+     * @param payload The application/json telemetry payload to be sent.
+     */
+    public void publishComponentTelemetry(String digitalTwinId, String componentName, String payload) {
+        TelemetryOptions telemetryOptions = new TelemetryOptions();
+        publishComponentTelemetry(digitalTwinId, componentName, payload, telemetryOptions);
+    }
+
+    /**
+     * Publishes telemetry from a digital twin's component
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param componentName The name of the DTDL component.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     */
+    public void publishComponentTelemetry(String digitalTwinId, String componentName, String payload, TelemetryOptions telemetryOptions) {
+        publishComponentTelemetryWithResponse(digitalTwinId, componentName, payload, telemetryOptions, Context.NONE);
+    }
+
+    /**
+     * Publishes telemetry from a digital twin's component
+     * The result is then consumed by one or many destination endpoints (subscribers) defined under {@link EventRoute}
+     * These event routes need to be set before publishing a telemetry message, in order for the telemetry message to be consumed.
+     * @param digitalTwinId The Id of the digital twin.
+     * @param componentName The name of the DTDL component.
+     * @param payload The application/json telemetry payload to be sent.
+     * @param telemetryOptions The additional information to be used when processing a telemetry request.
+     * @param context Additional context that is passed through the Http pipeline during the service call.
+     * @return A {@link Response}.
+     */
+    public Response<Void> publishComponentTelemetryWithResponse(String digitalTwinId, String componentName, String payload, TelemetryOptions telemetryOptions, Context context) {
+        return digitalTwinsAsyncClient.publishComponentTelemetryWithResponse(digitalTwinId, componentName, payload, telemetryOptions, context).block();
+    }
+
+    //endregion TelemetryAPIs
 }

sdk/digitaltwins/azure-digitaltwins-core/src/main/java/com/azure/digitaltwins/core/util/TelemetryOptions.java

@@ -0,0 +1,62 @@
+package com.azure.digitaltwins.core.util;
+
+import com.azure.core.annotation.Fluent;
+
+import java.time.OffsetDateTime;
+import java.time.ZoneOffset;
+import java.util.UUID;
+
+/**
+ * The additional information to be used when processing a telemetry request.
+ */
+@Fluent
+public final class TelemetryOptions {
+
+    /**
+     * A unique message identifier (within the scope of the digital twin id) that is commonly used for de-duplicating messages.
+     * Defaults to a random guid.
+     */
+    private String messageId = UUID.randomUUID().toString();
+
+    /**
+     * An RFC 3339 timestamp that identifies the time the telemetry was measured.
+     * It defaults to the current date/time UTC.
+     */
+    private OffsetDateTime timeStamp = OffsetDateTime.now(ZoneOffset.UTC);
+
+    /**
+     * Gets the message Id.
+     * @return A unique message identifier (within the scope of the digital twin id) that is commonly used for de-duplicating messages.
+     */
+    public String getMessageId() {
+        return this.messageId;
+    }
+
+    /**
+     * Gets the timestamp.
+     * @return The timestamp that identifies the time the telemetry was measured.
+     */
+    public OffsetDateTime getTimeStamp() {
+        return this.timeStamp;
+    }
+
+    /**
+     * Set the message Id
+     * @param messageId A unique message identifier (within the scope of the digital twin id) that is commonly used for de-duplicating messages.
+     * @return The TelemetryOption object itself.
+     */
+    public TelemetryOptions setMessageId(String messageId) {
+        this.messageId = messageId;
+        return this;
+    }
+
+    /**
+     * Set the timestamp
+     * @param timeStamp The timestamp that identifies the time the telemetry was measured.
+     * @return The TelemetryOption object itself.
+     */
+    public TelemetryOptions setTimeStamp(OffsetDateTime timeStamp) {
+        this.timeStamp = timeStamp;
+        return this;
+    }
+}