Interface ICoreClient

Namespace

Azure.Iot.Operations.Services.EdgeRegistry

Assembly

Azure.Iot.Operations.Services.dll

Client for the generic core xRegistry CRUD and query API over Groups, Resources, and Versions identified by XID path components. The extension clients (Schema, Thing Description, Thing Model) delegate to this surface for the group/resource/version operations that have no dedicated extension action.

public interface ICoreClient : IAsyncDisposable

Inherited Members

IAsyncDisposable.DisposeAsync()

Remarks

xRegistry models artifacts as a three-level hierarchy. Despite the generic names, the concepts are concrete:

• Group — a typed container (e.g. schemagroups) that holds Resources. The default groupId is the configured namespace; pass CloudDefault to use it, or a specific id for a custom Group.
• Resource — the named logical artifact (a schema, thing description, …) that owns an ordered set of Versions together with its meta attributes.
• Version — a single immutable revision of a Resource: it carries the document content and that revision's metadata (labels, validation status, hash, ancestor). A Version is not a semantic version; versionId is simply the identifier of the revision (a string in the core API, a service-assigned integer in the extensions). The newest revision is the Resource's default Version.

The full address of a revision is /{groupType}/{groupId}/{resourceType}/{resourceId}/versions/{versionId}. Creating a Version implicitly creates its parent Resource and Group when they do not yet exist.

Methods

CreateGroupAsync(string, GroupId, CoreGroupAttributes, TimeSpan?, CancellationToken)

Creates a Group.

Task<CoreGroupEntity> CreateGroupAsync(string groupType, GroupId groupId, CoreGroupAttributes attributes, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

attributes CoreGroupAttributes

The attributes of the Group to create.

timeout TimeSpan?

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

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<CoreGroupEntity>

A task whose result is the created CoreGroupEntity.

CreateResourceAsync(string, GroupId, string, string, CoreResourceMetaAttributes, Dictionary<string, byte[]>, CreateVersionId, CoreVersionAttributes, TimeSpan?, CancellationToken)

Creates a Resource together with its default Version.

Task<CoreResourceEntity> CreateResourceAsync(string groupType, GroupId groupId, string resourceType, string resourceId, CoreResourceMetaAttributes meta, Dictionary<string, byte[]> resourceExtensions, CreateVersionId defaultVersionId, CoreVersionAttributes defaultVersion, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

resourceType string

The Resource type (the xRegistry Resource collection name).

resourceId string

The Resource identifier.

meta CoreResourceMetaAttributes

The Resource-level metadata attributes.

resourceExtensions Dictionary<string, byte[]>

Resource-level extension attributes, keyed by extension name.

defaultVersionId CreateVersionId

The Version id to assign to the Resource's default Version. Use ServerAssigned to let the service choose.

defaultVersion CoreVersionAttributes

The attributes of the Resource's default 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<CoreResourceEntity>

A task whose result is the created CoreResourceEntity.

CreateVersionAsync(string, GroupId, string, string, IReadOnlyList<Label>, CreateVersionId, CoreVersionAttributes, TimeSpan?, CancellationToken)

Creates a Version under a Resource, implicitly creating the parent Resource if needed. Idempotent per the create-or-match-latest contract.

Task<CoreVersionEntity> CreateVersionAsync(string groupType, GroupId groupId, string resourceType, string resourceId, IReadOnlyList<Label> resourceLabels, CreateVersionId versionId, CoreVersionAttributes version, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

resourceType string

The Resource type (the xRegistry Resource collection name).

resourceId string

The owning Resource identifier.

resourceLabels IReadOnlyList<Label>

Labels applied to the parent Resource.

versionId CreateVersionId

The Version id to assign. Use ServerAssigned to let the service choose.

version CoreVersionAttributes

The attributes of the Version to create.

timeout TimeSpan?

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

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<CoreVersionEntity>

A task whose result is the created CoreVersionEntity.

DeleteGroupAsync(string, GroupId, DeleteOptions?, TimeSpan?, CancellationToken)

Deletes a Group. Deletes cascade to all contained Resources and their Versions.

Task DeleteGroupAsync(string groupType, GroupId groupId, DeleteOptions? options = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

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 Group has been deleted.

DeleteResourceAsync(string, GroupId, string, string, DeleteOptions?, TimeSpan?, CancellationToken)

Deletes a Resource. Deletes cascade to all of its Versions.

Task DeleteResourceAsync(string groupType, GroupId groupId, string resourceType, string resourceId, DeleteOptions? options = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

resourceType string

The Resource type (the xRegistry Resource collection name).

resourceId string

The Resource identifier.

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 Resource has been deleted.

DeleteVersionAsync(string, GroupId, string, string, string, DeleteOptions?, TimeSpan?, CancellationToken)

Deletes a specific Version of a Resource.

Task DeleteVersionAsync(string groupType, GroupId groupId, string resourceType, string resourceId, string versionId, DeleteOptions? options = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

resourceType string

The Resource type (the xRegistry Resource collection name).

resourceId string

The owning Resource identifier.

versionId string

The identifier of the 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 Version has been deleted.

GetGroupAsync(string, GroupId, TimeSpan?, CancellationToken)

Retrieves a Group.

Task<CoreGroupEntity> GetGroupAsync(string groupType, GroupId groupId, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

timeout TimeSpan?

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

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<CoreGroupEntity>

A task whose result is the requested CoreGroupEntity.

GetResourceAsync(string, GroupId, string, string, TimeSpan?, CancellationToken)

Retrieves a Resource.

Task<CoreResourceEntity> GetResourceAsync(string groupType, GroupId groupId, string resourceType, string resourceId, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

resourceType string

The Resource type (the xRegistry Resource collection name).

resourceId string

The Resource identifier.

timeout TimeSpan?

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

cancellationToken CancellationToken

A token to cancel the operation.

Returns

Task<CoreResourceEntity>

A task whose result is the requested CoreResourceEntity.

GetVersionAsync(string, GroupId, string, string, GetVersionId, TimeSpan?, CancellationToken)

Retrieves a Version. Pass ResourceDefault for the Resource's default (latest) Version.

Task<CoreVersionEntity> GetVersionAsync(string groupType, GroupId groupId, string resourceType, string resourceId, GetVersionId versionId, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

groupId GroupId

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

resourceType string

The Resource type (the xRegistry Resource collection name).

resourceId string

The owning Resource identifier.

versionId GetVersionId

The Version to retrieve. Use ResourceDefault for the Resource'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<CoreVersionEntity>

A task whose result is the requested CoreVersionEntity.

ListGroupsAsync(string, TimeSpan?, CancellationToken)

Lists the IDs of all Groups of the given groupType.

Task<IReadOnlyList<string>> ListGroupsAsync(string groupType, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groupType string

The Group type (the xRegistry Group collection name).

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<string>>

A task whose result is the IDs of all Groups of the given groupType.

ListResourcesAsync(GroupQuery, string?, Label?, TimeSpan?, CancellationToken)

Lists the XIDs of Resources matching the query, optionally filtered by Resource type and/or a single label.

Task<IReadOnlyList<ResourceXId>> ListResourcesAsync(GroupQuery groups, string? resourceType = null, Label? label = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groups GroupQuery

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

resourceType string

When set, restricts the results to this Resource type.

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<ResourceXId>>

A task whose result is the XIDs of the matching Resources.

ListVersionsAsync(GroupQuery, string?, string?, Label?, TimeSpan?, CancellationToken)

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

Task<IReadOnlyList<VersionXId>> ListVersionsAsync(GroupQuery groups, string? resourceType = null, string? resourceId = null, Label? label = null, TimeSpan? timeout = null, CancellationToken cancellationToken = default)

Parameters

groups GroupQuery

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

resourceType string

When set, restricts the results to this Resource type.

resourceId string

When set, restricts the results to this Resource.

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<VersionXId>>

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