com.microsoft.azure.sdk.iot.service.twin

Class TwinClient

java.lang.Object

com.microsoft.azure.sdk.iot.service.twin.TwinClient

public final class TwinClient
extends Object

Use the TwinClient class to manage the device twins in IoT hubs.

Constructor Summary

Constructors

Constructor and Description
TwinClient(String connectionString) Constructor to create instance from connection string.
TwinClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential) Create a new TwinClient instance.
TwinClient(String hostName, com.azure.core.credential.AzureSasCredential azureSasCredential, TwinClientOptions options) Create a new TwinClient instance.
TwinClient(String hostName, com.azure.core.credential.TokenCredential credential) Create a new TwinClient instance.
TwinClient(String hostName, com.azure.core.credential.TokenCredential credential, TwinClientOptions options) Create a new TwinClient instance.
TwinClient(String connectionString, TwinClientOptions options) Constructor to create instance from connection string.

Method Summary

Modifier and Type	Method and Description
Twin	get(String deviceId) This method retrieves device twin for the specified device.
Twin	get(String deviceId, String moduleId) This method retrieves device twin for the specified device.
Twin	patch(Twin twin) This method patches the twin for the specified device.
Twin	patch(Twin twin, String ifMatch) This method patches the twin for the specified device.
TwinQueryResponse	query(String query) Query from your IoT Hub's set of Twins.
TwinQueryResponse	query(String query, QueryPageOptions options) Query from your IoT Hub's set of Twins.
Twin	replace(Twin twin) Replace the full twin for a given device or module with the provided twin.
Twin	replace(Twin twin, String ifMatch) Replace the full twin for a given device or module with the provided twin.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TwinClient

public TwinClient(String connectionString)

Constructor to create instance from connection string.

Parameters:

connectionString - The iot hub connection string.

TwinClient

public TwinClient(String connectionString,
                  TwinClientOptions options)

Constructor to create instance from connection string.

Parameters:

connectionString - The iot hub connection string.

options - the configurable options for each operation on this client. May not be null.

TwinClient

public TwinClient(String hostName,
                  com.azure.core.credential.TokenCredential credential)

Create a new TwinClient instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

credential - The custom TokenCredential that will provide authentication tokens to this library when they are needed. The provided tokens must be Json Web Tokens.

TwinClient

public TwinClient(String hostName,
                  com.azure.core.credential.TokenCredential credential,
                  TwinClientOptions options)

Create a new TwinClient instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

credential - The custom TokenCredential that will provide authentication tokens to this library when they are needed. The provided tokens must be Json Web Tokens.

options - The connection options to use when connecting to the service.

TwinClient

public TwinClient(String hostName,
                  com.azure.core.credential.AzureSasCredential azureSasCredential)

Create a new TwinClient instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

azureSasCredential - The SAS token provider that will be used for authentication.

TwinClient

public TwinClient(String hostName,
                  com.azure.core.credential.AzureSasCredential azureSasCredential,
                  TwinClientOptions options)

Create a new TwinClient instance.

Parameters:

hostName - The hostname of your IoT Hub instance (For instance, "your-iot-hub.azure-devices.net")

azureSasCredential - The SAS token provider that will be used for authentication.

options - The connection options to use when connecting to the service.

Method Detail

get

public Twin get(String deviceId)
         throws IotHubException,
                IOException

This method retrieves device twin for the specified device.

Parameters:

deviceId - The id of the device whose twin will be retrieved.

Returns:

The retrieved twin object for the specified device.

Throws:

IOException - This exception is thrown if the IO operation failed.

IotHubException - This exception is thrown if the response verification failed.

get

public Twin get(String deviceId,
                String moduleId)
         throws IotHubException,
                IOException

This method retrieves device twin for the specified device.

Parameters:

deviceId - The id of the device whose twin will be retrieved.

moduleId - The id of the module on the device whose twin will be retrieved.

Returns:

The retrieved twin object for the specified module on the specified device.

Throws:

IOException - This exception is thrown if the IO operation failed.

IotHubException - This exception is thrown if the response verification failed.

patch

public Twin patch(Twin twin)
           throws IotHubException,
                  IOException

This method patches the twin for the specified device.

See PATCH for more details.

Parameters:

twin - The twin to be patched. To delete a particular property, set the value to null.

Throws:

IOException - This exception is thrown if the IO operation failed.

IotHubException - This exception is thrown if the response verification failed.

patch

public Twin patch(Twin twin,
                  String ifMatch)
           throws IotHubException,
                  IOException

This method patches the twin for the specified device.

See PATCH for more details.

Parameters:

twin - The twin to be patched. To delete a particular property, set the value to null.

ifMatch - the string representing a ETag for the device twin, as per RFC7232. If null, no if-match header will be sent as a part of this request and it will be executed unconditionally.

Throws:

IOException - This exception is thrown if the IO operation failed.

IotHubException - This exception is thrown if the response verification failed.

replace

public Twin replace(Twin twin)
             throws IotHubException,
                    IOException

Replace the full twin for a given device or module with the provided twin.

Parameters:

twin - The twin object to replace the current twin object.

Returns:

The Twin object's current state returned from the service after the replace operation.

Throws:

IotHubException - If any an IoT hub level exception is thrown. For instance, if the sendHttpRequest is unauthorized, a exception that extends IotHubException will be thrown.

IOException - If the sendHttpRequest failed to send to IoT hub.

replace

public Twin replace(Twin twin,
                    String ifMatch)
             throws IotHubException,
                    IOException

Replace the full twin for a given device or module with the provided twin.

Parameters:

twin - The twin object to replace the current twin object.

ifMatch - the string representing a ETag for the device twin, as per RFC7232. If null, no if-match header will be sent as a part of this request and it will be executed unconditionally.

Returns:

The Twin object's current state returned from the service after the replace operation.

Throws:

IotHubException - If any an IoT hub level exception is thrown. For instance, if the sendHttpRequest is unauthorized, an exception that extends IotHubException will be thrown.

IOException - If the sendHttpRequest failed to send to IoT hub.

query

public TwinQueryResponse query(String query)
                        throws IOException,
                               IotHubException

Query from your IoT Hub's set of Twins.

Parameters:

query - The IoT Hub query for selecting which twins to getJob.

Returns:

The pageable set of Twins that were queried.

Throws:

IOException - If IoT Hub cannot be reached due to network level issues.

IotHubException - If the request fails for non-network level issues such as an incorrectly formatted query.

See Also:

IoT Hub query language

query

public TwinQueryResponse query(String query,
                               QueryPageOptions options)
                        throws IOException,
                               IotHubException

Query from your IoT Hub's set of Twins.

Parameters:

query - The IoT Hub query for selecting which twins to getJob.

options - The optional parameters used to decide how the query's results are returned. May not be null.

Returns:

The pageable set of Twins that were queried.

Throws:

IOException - If IoT Hub cannot be reached due to network level issues.

IotHubException - If the request fails for non-network level issues such as an incorrectly formatted query.

See Also:

IoT Hub query language