Skip to content

Delete devices APIs from API design doc now that they are implemented #12699

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Delete devices APIs from API design doc now that they are implemented #12699

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
212 changes: 1 addition & 211 deletions sdk/iot/Azure.Iot.Hub.Service/src/API Design.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,218 +41,8 @@ APIs for getting statistics about devices and modules, as well as service statis
<details><summary><b>Devices</b></summary>
APIs for managing device identities, device twins, and querying devices

```csharp
public class Devices
{
/// <summary>
/// Create or update a device identity.
/// </summary>
/// <param name="deviceIdentity">the device identity to create.</param>
/// <param name="precondition">The condition on which to perform this operation. To create a device identity, this value must be equal to <see cref="IfMatchPrecondition.Unconditional"/>.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The created device identity.</returns>
public virtual Task<Response<DeviceIdentity>> CreateOrUpdateIdentityAsync(DeviceIdentity deviceIdentity, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Create or update a device identity.
/// </summary>
/// <param name="deviceIdentity">the device identity to create.</param>
/// <param name="precondition">The condition on which to perform this operation. To create a device identity, this value must be equal to <see cref="IfMatchPrecondition.Unconditional"/>.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The created device identity.</returns>
public virtual Response<DeviceIdentity> CreateOrUpdateIdentity(DeviceIdentity deviceIdentity, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Get a single device identity.
/// </summary>
/// <param name="deviceId">The unique identifier of the device identity to get.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The retrieved device identity.</returns>
public virtual Task<Response<DeviceIdentity>> GetIdentityAsync(string deviceId, CancellationToken cancellationToken = default)

/// <summary>
/// Get a single device identity.
/// </summary>
/// <param name="deviceId">The unique identifier of the device identity to get.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The retrieved device identity.</returns>
public virtual Response<DeviceIdentity> GetIdentity(string deviceId, CancellationToken cancellationToken = default)

/// <summary>
/// Delete a single device identity.
/// </summary>
/// <param name="deviceIdentity">the device identity to delete. If no ETag is present on the device, then the condition must be equal to <see cref="IfMatchPrecondition.Unconditional"/> or equal to <see cref="IfMatchPrecondition.UnconditionalIfMatch"/></param>
/// <param name="precondition">The condition on which to delete the device.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The http response.</returns>
public virtual Task<Response> DeleteIdentityAsync(DeviceIdentity deviceIdentity, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Delete a single device identity.
/// </summary>
/// <param name="deviceIdentity">the device identity to delete. If no ETag is present on the device, then the condition must be equal to <see cref="IfMatchPrecondition.Unconditional"/> or equal to <see cref="IfMatchPrecondition.UnconditionalIfMatch"/></param>
/// <param name="precondition">The condition on which to delete the device.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The http response.</returns>
public virtual Response DeleteIdentity(DeviceIdentity deviceIdentity, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Create multiple devices with an initial twin. A maximum of 100 creations can be done per call, and each creation must have a unique device identity. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="devices">The pairs of devices their twins that will be created. For fields such as deviceId
/// where device and twin have a definition, the device value will override the twin value.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Task<Response<BulkRegistryOperationResponse>> CreateIdentitiesWithTwinAsync(IDictionary<DeviceIdentity, TwinData> devices, CancellationToken cancellationToken = default)

/// <summary>
/// Create multiple devices with an initial twin. A maximum of 100 creations can be done per call, and each creation must have a unique device identity. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="devices">The pairs of devices their twins that will be created. For fields such as deviceId
/// where device and twin have a definition, the device value will override the twin value.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Response<BulkRegistryOperationResponse> CreateIdentitiesWithTwin(IDictionary<DeviceIdentity, TwinData> devices, CancellationToken cancellationToken = default)

/// <summary>
/// Create multiple devices. A maximum of 100 creations can be done per call, and each device identity must be unique. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="deviceIdentities">The devices identities to create.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Task<Response<BulkRegistryOperationResponse>> CreateIdentitiesAsync(IEnumerable<DeviceIdentity> deviceIdentities, CancellationToken cancellationToken = default)

/// <summary>
/// Create multiple devices. A maximum of 100 creations can be done per call, and each device identity must be unique. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="deviceIdentities">The device identities to create.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Response<BulkRegistryOperationResponse> CreateIdentities(IEnumerable<DeviceIdentity> deviceIdentities, CancellationToken cancellationToken = default)

/// <summary>
/// Update multiple devices. A maximum of 100 updates can be done per call, and each operation must be done on a different identity. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>..
/// </summary>
/// <param name="deviceIdentities">The devices to update.</param>
/// <param name="precondition">The condition on which to update each device identity.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Task<Response<BulkRegistryOperationResponse>> UpdateIdentiesAsync(IEnumerable<DeviceIdentity> deviceIdentities, BulkIfMatchPrecondition precondition = BulkIfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Update multiple devices. A maximum of 100 updates can be done per call, and each operation must be done on a different identity. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="deviceIdentities">The devices to update.</param>
/// <param name="precondition">The condition on which to update each device identity.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Response<BulkRegistryOperationResponse> UpdateIdenties(IEnumerable<DeviceIdentity> deviceIdentities, BulkIfMatchPrecondition precondition = BulkIfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Delete multiple devices. A maximum of 100 deletions can be done per call. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="deviceIdentities">The devices to delete.</param>
/// <param name="precondition">The condition on which to delete each device identity.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk deletion.</returns>
public virtual Task<Response<BulkRegistryOperationResponse>> DeleteIdentitiesAsync(IEnumerable<DeviceIdentity> deviceIdentities, BulkIfMatchPrecondition precondition = BulkIfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Delete multiple devices. A maximum of 100 deletions can be done per call. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="deviceIdentities">The devices to delete.</param>
/// <param name="precondition">The condition on which to delete each device identity.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk deletion.</returns>
public virtual Response<BulkRegistryOperationResponse> DeleteIdentities(IEnumerable<DeviceIdentity> deviceIdentities, BulkIfMatchPrecondition precondition = BulkIfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// List a set of device twins.
/// </summary>
/// <param name="pageSize">The size of each page to be retrieved from the service. Service may override this size.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>A pageable set of device twins.</returns>
public virtual AsyncPageable<TwinData> GetTwinsAsync(int? pageSize = null, CancellationToken cancellationToken = default)

/// <summary>
/// List a set of device twins.
/// </summary>
/// <param name="pageSize">The size of each page to be retrieved from the service. Service may override this size.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>A pageable set of device twins.</returns>
public virtual Pageable<TwinData> GetTwins(int? pageSize = null, CancellationToken cancellationToken = default)

/// <summary>
/// Get a device's twin.
/// </summary>
/// <param name="deviceId">The unique identifier of the device identity to get the twin of.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The device's twin, including reported properties and desired properties.</returns>
public virtual Task<Response<TwinData>> GetTwinAsync(string deviceId, CancellationToken cancellationToken = default)

/// <summary>
/// Get a device's twin.
/// </summary>
/// <param name="deviceId">The unique identifier of the device identity to get the twin of.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The device's twin, including reported properties and desired properties.</returns>
public virtual Response<TwinData> GetTwin(string deviceId, CancellationToken cancellationToken = default)

/// <summary>
/// Update a device's twin.
/// </summary>
/// <param name="twinUpdate">The properties to update. Any existing properties not referenced by this patch will be unaffected by this patch.</param>
/// <param name="precondition">The condition for which this operation will execute.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The new representation of the device twin.</returns>
public virtual Task<Response<TwinData>> UpdateTwinAsync(TwinData twinUpdate, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Update a device's twin.
/// </summary>
/// <param name="twinUpdate">The properties to update. Any existing properties not referenced by this patch will be unaffected by this patch.</param>
/// <param name="precondition">The condition for which this operation will execute.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The new representation of the device twin.</returns>
public virtual Response<TwinData> UpdateTwin(TwinData twinUpdate, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Update multiple devices' twins. A maximum of 100 updates can be done per call, and each operation must be done on a different device twin. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="twinUpdates">The new twins to replace the twins on existing devices.</param>
/// <param name="precondition">The condition on which to update each device twin.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Task<Response<BulkRegistryOperationResponse>> UpdateTwinsAsync(IEnumerable<TwinData> twinUpdates, BulkIfMatchPrecondition precondition = BulkIfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)

/// <summary>
/// Update multiple devices' twins. A maximum of 100 updates can be done per call, and each operation must be done on a different device twin. For larger scale operations, consider using <see href="https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-identity-registry#import-and-export-device-identities">IoT Hub jobs</see>.
/// </summary>
/// <param name="twinUpdates">The new twins to replace the twins on existing devices.</param>
/// <param name="precondition">The condition on which to update each device twin.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the bulk operation.</returns>
public virtual Response<BulkRegistryOperationResponse> UpdateTwins(IEnumerable<TwinData> twinUpdates, BulkIfMatchPrecondition precondition = BulkIfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default)
This namespace has already been implemented. See DevicesClient.cs for code.

/// <summary>
/// Invoke a method on a device.
/// </summary>
/// <param name="deviceId">The unique identifier of the device identity to invoke the method on.</param>
/// <param name="directMethodRequest">The details of the method to invoke.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the method invocation.</returns>
public virtual Task<Response<CloudToDeviceMethodResponse>> InvokeMethodAsync(string deviceId, CloudToDeviceMethodRequest directMethodRequest, CancellationToken cancellationToken = default)

/// <summary>
/// Invoke a method on a device.
/// </summary>
/// <param name="deviceId">The unique identifier of the device identity to invoke the method on.</param>
/// <param name="directMethodRequest">The details of the method to invoke.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The result of the method invocation.</returns>
public virtual Response<CloudToDeviceMethodResponse> InvokeMethod(string deviceId, CloudToDeviceMethodRequest directMethodRequest, CancellationToken cancellationToken = default)
}
```
</details>

<details><summary><b>Modules</b></summary>
Expand Down