EventGrid data spec for Microsoft.Devices/Iothub #2424
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,274 @@ | ||
| { | ||
| "swagger": "2.0", | ||
| "info": { | ||
| "version": "2018-01-01", | ||
| "title": "Schema of Azure IoT Hub events published to Azure Event Grid", | ||
| "description": | ||
| "Describes the schema of the Azure IoT Hub events published to Azure Event Grid. This corresponds to the Data property of an EventGridEvent." | ||
| }, | ||
| "paths": {}, | ||
| "definitions": { | ||
| "IotHubDeviceCreatedEventData": { | ||
|
Contributor
There was a problem hiding this comment. Looks like you are sharing a bunch of properties with |
||
| "type": "object", | ||
| "description": "Schema of the Data property of an EventGridEvent for an Microsoft.Devices.DeviceCreated event.", | ||
| "properties": { | ||
| "deviceId": { | ||
| "type": "string", | ||
| "description": | ||
| "The unique identifier of the device. This case-sensitive string can be up to 128 characters long, and supports ASCII 7-bit alphanumeric characters plus the following special characters: - : . + % _ # * ? ! ( ) , = @ ; $ '." | ||
| }, | ||
| "hubName": { | ||
| "type": "string", | ||
| "description": "Name of the IoT Hub where the device was created or deleted." | ||
| }, | ||
| "opType": { | ||
| "type": "string", | ||
| "description": "The event type specified for this operation by the IoT Hub." | ||
| }, | ||
| "operationTimestamp": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the operation." | ||
| }, | ||
| "twin": { | ||
| "type": "object", | ||
| "description": | ||
| "Information about the device twin, which is the cloud represenation of application device metadata.", | ||
| "properties": { | ||
| "authenticationType": { | ||
| "type": "string", | ||
| "description": | ||
| "Authentication type used for this device: either SAS, SelfSigned, or CertificateAuthority." | ||
| }, | ||
| "cloudToDeviceMessageCount": { | ||
| "type": "number", | ||
| "description": "Count of cloud to device messages sent to this device." | ||
| }, | ||
| "connectionState": { | ||
| "type": "string", | ||
| "description": "Whether the device is connected or disconnected." | ||
| }, | ||
| "deviceId": { | ||
| "type": "string", | ||
| "description": "The unique identifier of the device twin." | ||
| }, | ||
| "etag": { | ||
| "type": "string", | ||
| "description": | ||
| "A piece of information that describes the content of the device twin. Each etag is guaranteed to be unique per device twin." | ||
| }, | ||
| "lastActivityTime": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last activity." | ||
| }, | ||
| "properties": { | ||
| "type": "object", | ||
| "description": "Properties JSON element.", | ||
| "properties": { | ||
| "desired": { | ||
| "type": "object", | ||
| "description": | ||
| "A portion of the properties that can be written only by the application back-end, and read by the device.", | ||
| "properties": { | ||
|
Contributor
There was a problem hiding this comment. A. We discourage use of inline definitions for complex object properties.
Contributor
There was a problem hiding this comment. Also, you are repeating this definition again in
Contributor
Author
There was a problem hiding this comment. Yes, the model has properties with "$" to signify that they are system properties.
Contributor
There was a problem hiding this comment. If these are not odata properties, we strongly recommend using |
||
| "$metadata": { | ||
| "type": "object", | ||
| "description": "Metadata information for the properties JSON document.", | ||
| "properties": { | ||
| "$lastUpdated": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last time the properties were updated." | ||
| } | ||
| } | ||
| }, | ||
| "$version": { | ||
| "type": "number", | ||
| "description": "Version of device twin properties." | ||
| } | ||
| } | ||
| }, | ||
| "reported": { | ||
| "type": "object", | ||
| "description": | ||
| "A portion of the properties that can be written only by the device, and read by the application back-end.", | ||
| "properties": { | ||
| "$metadata": { | ||
| "type": "object", | ||
| "description": "Metadata information for the properties JSON document.", | ||
| "properties": { | ||
| "$lastUpdated": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last time the properties were updated." | ||
| } | ||
| } | ||
| }, | ||
| "$version": { | ||
| "type": "number", | ||
| "description": "Version of device twin properties." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "status": { | ||
| "type": "string", | ||
| "description": "Whether the device twin is enabled or disabled." | ||
| }, | ||
| "statusUpdateTime": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last device twin status update." | ||
| }, | ||
| "version": { | ||
| "type": "number", | ||
| "description": "An integer that is incremented by one each time the device twin is updated." | ||
| }, | ||
| "x509Thumbprint": { | ||
| "type": "object", | ||
| "description": | ||
| "The thumbprint is a unique value for the x509 certificate, commonly used to find a particular certificate in a certificate store. The thumbprint is dynamically generated using the SHA1 algorithm, and does not physically exist in the certificate.", | ||
| "properties": { | ||
| "primaryThumbprint": { | ||
| "type": "string", | ||
| "description": "Primary thumbprint for the x509 certificate." | ||
| }, | ||
| "secondaryThumbprint": { | ||
| "type": "string", | ||
| "description": "Secondary thumbprint for the x509 certificate." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "IotHubDeviceDeletedEventData": { | ||
| "type": "object", | ||
| "description": "Schema of the Data property of an EventGridEvent for an Microsoft.Devices.DeviceDeleted event.", | ||
| "properties": { | ||
| "deviceId": { | ||
| "type": "string", | ||
| "description": | ||
| "The unique identifier of the device. This case-sensitive string can be up to 128 characters long, and supports ASCII 7-bit alphanumeric characters plus the following special characters: - : . + % _ # * ? ! ( ) , = @ ; $ '." | ||
| }, | ||
| "hubName": { | ||
| "type": "string", | ||
| "description": "Name of the IoT Hub where the device was created or deleted." | ||
| }, | ||
| "opType": { | ||
| "type": "string", | ||
| "description": "The event type specified for this operation by the IoT Hub." | ||
| }, | ||
| "operationTimestamp": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the operation." | ||
| }, | ||
| "twin": { | ||
| "type": "object", | ||
| "description": | ||
| "Information about the device twin, which is the cloud represenation of application device metadata.", | ||
| "properties": { | ||
|
Contributor
There was a problem hiding this comment. As before, please do not define inline properties like so, create a new definition |
||
| "authenticationType": { | ||
| "type": "string", | ||
| "description": | ||
| "Authentication type used for this device: either SAS, SelfSigned, or CertificateAuthority." | ||
| }, | ||
| "cloudToDeviceMessageCount": { | ||
| "type": "number", | ||
| "description": "Count of cloud to device messages sent to this device." | ||
| }, | ||
| "connectionState": { | ||
| "type": "string", | ||
| "description": "Whether the device is connected or disconnected." | ||
| }, | ||
| "deviceId": { | ||
| "type": "string", | ||
| "description": "The unique identifier of the device twin." | ||
| }, | ||
| "etag": { | ||
| "type": "string", | ||
| "description": | ||
| "A piece of information that describes the content of the device twin. Each etag is guaranteed to be unique per device twin." | ||
| }, | ||
| "lastActivityTime": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last activity." | ||
| }, | ||
| "properties": { | ||
| "type": "object", | ||
| "description": "Properties JSON element.", | ||
| "properties": { | ||
| "desired": { | ||
| "type": "object", | ||
| "description": | ||
| "A portion of the properties that can be written only by the application back-end, and read by the device.", | ||
| "properties": { | ||
| "$metadata": { | ||
| "type": "object", | ||
| "description": "Metadata information for the properties JSON document.", | ||
| "properties": { | ||
| "$lastUpdated": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last time the properties were updated." | ||
| } | ||
| } | ||
| }, | ||
| "$version": { | ||
| "type": "number", | ||
| "description": "Version of device twin properties." | ||
| } | ||
| } | ||
| }, | ||
| "reported": { | ||
| "type": "object", | ||
| "description": | ||
| "A portion of the properties that can be written only by the device, and read by the application back-end.", | ||
| "properties": { | ||
| "$metadata": { | ||
| "type": "object", | ||
| "description": "Metadata information for the properties JSON document.", | ||
| "properties": { | ||
| "$lastUpdated": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last time the properties were updated." | ||
| } | ||
| } | ||
| }, | ||
| "$version": { | ||
| "type": "number", | ||
| "description": "Version of device twin properties." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "status": { | ||
| "type": "string", | ||
| "description": "Whether the device twin is enabled or disabled." | ||
| }, | ||
| "statusUpdateTime": { | ||
| "type": "string", | ||
| "description": "The ISO8601 timestamp of the last device twin status update." | ||
| }, | ||
| "version": { | ||
| "type": "number", | ||
| "description": "An integer that is incremented by one each time the device twin is updated." | ||
| }, | ||
| "x509Thumbprint": { | ||
| "type": "object", | ||
| "description": | ||
| "The thumbprint is a unique value for the x509 certificate, commonly used to find a particular certificate in a certificate store. The thumbprint is dynamically generated using the SHA1 algorithm, and does not physically exist in the certificate.", | ||
| "properties": { | ||
| "primaryThumbprint": { | ||
| "type": "string", | ||
| "description": "Primary thumbprint for the x509 certificate." | ||
| }, | ||
| "secondaryThumbprint": { | ||
| "type": "string", | ||
| "description": "Secondary thumbprint for the x509 certificate." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So if I understand correctly, you are simply defining models but not any paths from the service. What is the intention here?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is used to document the schemas of the various events published to EventGrid. A consumer who is consuming events from EventGrid (e.g. in an Azure function or in any webhook) can use the generated classes to deserialize the event appropriately. This is the same pattern used for other existing event schemas as well (e.g. the storage events in the eventgrid data plane directory).
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the explanation.