Interface IThingDescriptionClient

Namespace

Azure.Iot.Operations.Services.EdgeRegistry

Assembly

Azure.Iot.Operations.Services.dll

Client for the xRegistry Thing Description extension: create, retrieve, list, and delete Thing Description Versions. Thing Description Versions use integer (ulong) version identifiers assigned by the service. The parent Thing Description (Resource) and Thing Description Group are implicitly created when a Version is created.

public interface IThingDescriptionClient

Remarks

The Thing Description extension is the core xRegistry model specialized for WoT Thing Descriptions; the generic concepts map directly (see ICoreClient):

• Thing Description Group = xRegistry Group (thingdescriptiongroups).
• Thing Description = xRegistry Resource — the named Thing Description that owns its revisions.
• Thing Description Version = xRegistry Version — one immutable revision of a Thing Description document. ThingDescriptionVersion carries the document bytes plus the revision's metadata; its versionId is a service-assigned integer, not a semantic version.

Methods

CreateThingDescriptionVersionAsync(GroupId, string, IReadOnlyList<Label>, ThingDescriptionVersionAttributes, CreateOptions?, TimeSpan?, CancellationToken)

Creates a Thing Description Version under the given Thing Description, implicitly creating the parent Thing Description if needed.

Task<ThingDescriptionVersion> CreateThingDescriptionVersionAsync(GroupId groupId, string thingDescriptionId, IReadOnlyList<Label> thingDescriptionLabels, ThingDescriptionVersionAttributes version, CreateOptions? options = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupId GroupId

The Thing Description Group. Use CloudDefault for the cloud-default Group (the configured namespace).

thingDescriptionId string

The Thing Description (Resource) identifier.

thingDescriptionLabels IReadOnlyList<Label>

Labels applied to the parent Thing Description.

version ThingDescriptionVersionAttributes

The attributes of the Thing Description Version to create.

options CreateOptions

The CreateOptions that control the behavior of the create operation; when null, the created entity is persisted.

timeout TimeSpan?

The command timeout; when null, the client's default timeout is used.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<ThingDescriptionVersion>

A task whose result is the created ThingDescriptionVersion.

DeleteThingDescriptionVersionAsync(GroupId, string, ulong, DeleteOptions?, TimeSpan?, CancellationToken)

Deletes a specific Thing Description Version.

Task DeleteThingDescriptionVersionAsync(GroupId groupId, string thingDescriptionId, ulong versionId, DeleteOptions? options = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupId GroupId

The Thing Description Group. Use CloudDefault for the cloud-default Group (the configured namespace).

thingDescriptionId string

The Thing Description (Resource) identifier.

versionId ulong

The identifier of the Thing Description Version to delete.

options DeleteOptions

The DeleteOptions that control the behavior of the delete operation; when null, Default is used.

timeout TimeSpan?

The command timeout; when null, the client's default timeout is used.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task

A task that completes when the Thing Description Version has been deleted.

GetThingDescriptionVersionAsync(GroupId, string, GetThingDescriptionVersionId, TimeSpan?, CancellationToken)

Retrieves a Thing Description Version.

Task<ThingDescriptionVersion> GetThingDescriptionVersionAsync(GroupId groupId, string thingDescriptionId, GetThingDescriptionVersionId versionId, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupId GroupId

The Thing Description Group. Use CloudDefault for the cloud-default Group (the configured namespace).

thingDescriptionId string

The Thing Description (Resource) identifier.

versionId GetThingDescriptionVersionId

The Version to retrieve. Use ResourceDefault for the Thing Description's default (latest) Version.

timeout TimeSpan?

The command timeout; when null, the client's default timeout is used.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<ThingDescriptionVersion>

A task whose result is the requested ThingDescriptionVersion.

ListThingDescriptionVersionsAsync(GroupSelector, string?, string?, Label?, TimeSpan?, CancellationToken)

Lists the XIDs of Thing Description Versions matching the query, optionally filtered by Thing Description id and/or a single label.

Task<IReadOnlyList<ThingDescriptionVersionXid>> ListThingDescriptionVersionsAsync(GroupSelector groups, string? thingDescriptionId = null, string? documentHash = null, Label? label = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groups GroupSelector

The Groups to search; see GroupSelector for the available scopes.

thingDescriptionId string

When set, restricts the results to this Thing Description.

documentHash string

When set, restricts the results to entities whose document has this hash.

label Label

When set, restricts the results to entities carrying this label.

timeout TimeSpan?

The command timeout; when null, the client's default timeout is used.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<IReadOnlyList<ThingDescriptionVersionXid>>

A task whose result is the XIDs of the matching Thing Description Versions.

ListThingDescriptionsAsync(GroupSelector, Label?, TimeSpan?, CancellationToken)

Lists the XIDs of Thing Descriptions matching the query, optionally filtered by a single label.

Task<IReadOnlyList<ResourceXId>> ListThingDescriptionsAsync(GroupSelector groups, Label? label = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groups GroupSelector

The Thing Description Groups to search; see GroupSelector for the available scopes.

label Label

When set, restricts the results to Thing Descriptions carrying this label.

timeout TimeSpan?

The command timeout; when null, the client's default timeout is used.

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<IReadOnlyList<ResourceXId>>

A task whose result is the XIDs of the matching Thing Descriptions.