Skip to content

(feat): Implement Modules client #12673

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

Merged
merged 18 commits into from
Jun 10, 2020
Merged

(feat): Implement Modules client #12673

Show file tree
Hide file tree
Changes from 10 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
9b79574
Implement Modules client
azabbasi Jun 9, 2020
54ce8ed
Update API Design.md
azabbasi Jun 9, 2020
03a0a15
Fix all warnings and make sure solution builds
azabbasi Jun 10, 2020
fe3fffb
Format files
azabbasi Jun 10, 2020
d59e7d7
remove unnecessary code
azabbasi Jun 10, 2020
7cce057
cr comments
azabbasi Jun 10, 2020
ad24b72
reference http response type
azabbasi Jun 10, 2020
2108d2a
update async pagable comments
azabbasi Jun 10, 2020
743404b
update module client summary
azabbasi Jun 10, 2020
10a089f
add link to the summary
azabbasi Jun 10, 2020
6b19d7c
Update Readme to pass code analysys
azabbasi Jun 10, 2020
c6a9f1a
Update README.md
azabbasi Jun 10, 2020
86312b1
Export APIs
azabbasi Jun 10, 2020
8fa846b
make query string constant
azabbasi Jun 10, 2020
b904adc
Update API design md file to reference implementation.
azabbasi Jun 10, 2020
7d9f736
xml comments for protector constructor
azabbasi Jun 10, 2020
c38b517
Update xml comments.
azabbasi Jun 10, 2020
628e9ff
fix typo
azabbasi Jun 10, 2020
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
105 changes: 54 additions & 51 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
@@ -1,9 +1,10 @@
# Azure Iot Hub Service API Design Doc

This document outlines the APIs for the Azure Iot Hub Service SDK

<details><summary><b>Type definition names</b></summary>
```

```text
Configuration - TwinConfiguration
Module - ModuleIdentity
Device - DeviceIdentity
Expand All @@ -13,21 +14,25 @@ Property - PnpProperty
Reported - PnpReported
Desired - PnpDesired
```

</details>

<details><summary><b>Constructors</b></summary>

```csharp

```

</details>

<details><summary><b>Configurations</b></summary>

APIs for managing configurations for devices and modules

```csharp

```

</details>

<details><summary><b>Statistics</b></summary>
Expand All @@ -36,6 +41,7 @@ APIs for getting statistics about devices and modules, as well as service statis
```csharp

```

</details>

<details><summary><b>Devices</b></summary>
Expand Down Expand Up @@ -253,6 +259,7 @@ public class Devices
public virtual Response<CloudToDeviceMethodResponse> InvokeMethod(string deviceId, CloudToDeviceMethodRequest directMethodRequest, CancellationToken cancellationToken = default)
}
```

</details>

<details><summary><b>Modules</b></summary>
Expand All @@ -263,91 +270,87 @@ APIs for managing module identities, module twins, and querying modules
public class Modules
{
/// <summary>
/// Create a device module identity.
/// Create a module identity.
/// </summary>
/// <param name="moduleIdentity">The module to create.</param>
/// <param name="moduleIdentity">The module identity to create.</param>
/// <param name="precondition">The condition on which to perform this operation. To create a module identity, this value must be equal to <see cref="IfMatchPrecondition.Unconditional"/>.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The newly created device module identity</returns>
public virtual async Task<Response<ModuleIdentity>> CreateIdentityAsync(ModuleIdentity moduleIdentity, CancellationToken cancellationToken = default);
/// <returns>The created module identity.</returns>
public virtual Task<Response<ModuleIdentity>> CreateOrUpdateIdentityAsync(ModuleIdentity moduleIdentity, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default);

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

/// <summary>
/// List a set of device's module identities.
/// Get a set of module identities for a specific device.
/// </summary>
/// <param name="deviceId">The unique identifier of the device.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>A pageable set of device module identities.</returns>
public virtual async Task<Response<IReadOnlyList<ModuleIdentity>>> GetIdentitiesAsync(string deviceId, CancellationToken cancellationToken = default);
/// <returns>A list of modules identities within a device.</returns>
public virtual Task<Response<IReadOnlyList<ModuleIdentity>>> GetIdentitiesAsync(string deviceId, CancellationToken cancellationToken = default);

/// <summary>
/// Update a device module identity.
/// Delete a single module identity.
/// </summary>
/// <param name="moduleIdentity">The module to update.</param>
/// <param name="ifMatch">A string representing a weak ETag for this module, as per RFC7232. The update operation is performed
/// only if this ETag matches the value maintained by the server, indicating that the module has not been modified since it was last retrieved.
/// The current ETag can be retrieved from the module identity last retrieved from the service. To force an unconditional update, set If-Match to the wildcard character (*).</param>
/// <param name="moduleIdentity">The module identity to delete. If no ETag is present on the module identity, 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 module identity.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The updated device module identity.</returns>
public virtual async Task<Response<ModuleIdentity>> UpdateIdentityAsync(ModuleIdentity moduleIdentity, string ifMatch = null, CancellationToken cancellationToken = default);
/// <returns>The http response.</returns>
public virtual Task<Response> DeleteIdentityAsync(ModuleIdentity moduleIdentity, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default);

/// <summary>
/// Delete a single device module identity.
/// Delete a single module identity.
/// </summary>
/// <param name="deviceId">The unique identifier of the device that contains the module.</param>
/// <param name="moduleId">The unique identifier of the module to get.</param>
/// <param name="ifMatch">A string representing a weak ETag for this module, as per RFC7232. The update operation is performed
/// only if this ETag matches the value maintained by the server, indicating that the module has not been modified since it was last retrieved.
/// The current ETag can be retrieved from the module identity last retrieved from the service. To force an unconditional update, set If-Match to the wildcard character (*).</param>
/// <param name="moduleIdentity">The module identity to delete. If no ETag is present on the module identity, 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 module identity.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>The http response.</returns>
public virtual async Task<Response> DeleteIdentityAsync(string deviceId, string moduleId, string ifMatch = null, CancellationToken cancellationToken = default);
public virtual Response DeleteIdentity(ModuleIdentity moduleIdentity, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default);

/// <summary>
/// Get a device module twin.
/// List a set of module twins.
/// </summary>
/// <param name="deviceId">The unique identifier of the device.</param>
/// <param name="moduleId">The unique identifier of the device module.</param>
/// <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>The retrieved module twin.</returns>
public virtual async Task<Response<TwinData>> GetTwinAsync(string deviceId, string moduleId, CancellationToken cancellationToken = default);
/// <returns>A pageable set of module twins.</returns>
public virtual AsyncPageable<TwinData> GetTwinsAsync(int? pageSize = null, CancellationToken cancellationToken = default);

/// <summary>
/// List a set of device module twins.
/// Get a module's twin.
/// </summary>
/// <param name="deviceId">The unique identifier of the device identity.</param>
/// <param name="moduleId">The unique identifier of the module identity.</param>
/// <param name="cancellationToken">The cancellation token.</param>
/// <returns>A pageable set of device module twins.</returns>
public virtual async AsyncPageable<TwinData> GetTwinsAsync(CancellationToken cancellationToken = default);
/// <returns>The module's twin, including reported properties and desired properties.</returns>
public virtual Task<Response<TwinData>> GetTwinAsync(string deviceId, string moduleId, CancellationToken cancellationToken = default);

/// <summary>
/// Update a module's twin.
/// </summary>
/// <param name="twinPatch">The properties to update. Any existing properties not referenced by this patch will be unaffected by this patch.</param>
/// <param name="ifMatch">A string representing a weak ETag for this twin, as per RFC7232. The update operation is performed
/// only if this ETag matches the value maintained by the server, indicating that the twin has not been modified since it was last retrieved.
/// To force an unconditional update, set If-Match to the wildcard character (*).</param>
/// <param name="cancellationToken">The cancellation token</param>
/// <returns>The server's new representation of the device module twin.</returns>
public virtual async Task<Response<TwinData>> UpdateTwinAsync(TwinData twinPatch, string ifMatch = null, CancellationToken cancellationToken = default);
/// <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 module's twin.</returns>
public virtual Task<Response<TwinData>> UpdateTwinAsync(TwinData twinUpdate, IfMatchPrecondition precondition = IfMatchPrecondition.IfMatch, CancellationToken cancellationToken = default);

/// <summary>
/// Invoke a method on a device module.
/// Invoke a method on a module.
/// </summary>
/// <param name="deviceId">The unique identifier of the device that contains the module.</param>
/// <param name="moduleId">The unique identifier of the module.</param>
/// <param name="deviceId">The unique identifier of the device.</param>
/// <param name="moduleId">The unique identifier of the module 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 async Task<Response<CloudToDeviceMethodResponse>> InvokeMethodAsync(string deviceId, string moduleId, CloudToDeviceMethodRequest cloudToDeviceMethodRequest, CancellationToken cancellationToken = default);
public virtual Task<Response<CloudToDeviceMethodResponse>> InvokeMethodAsync(string deviceId, string moduleId, CloudToDeviceMethodRequest directMethodRequest, CancellationToken cancellationToken = default);
}
```

</details>

<details><summary><b>Jobs</b></summary>
Expand All @@ -356,35 +359,35 @@ APIs for using IotHub v2 jobs
```csharp

```

</details>

<details><summary><b>Messages</b></summary>
Feedback messages, sending cloud to device messages (missing from current swagger), and purging cloud to device message queue
```csharp

```
</details>

<details><summary><b>Files</b></summary>
APIs for getting file upload notifications (missing from current swagger)

```csharp

```

</details>

<details><summary><b>Fault Injection</b></summary>
Not sure if we'll expose these

```csharp

```

</details>

<details><summary><b>Query</b></summary>
APIs for querying on device or module identities

```csharp

```

</details>
Loading