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,150 @@ | ||
| { | ||
| "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 |
||
| "description": "Schema of the Data property of an EventGridEvent for a Microsoft.Devices.DeviceCreated event.", | ||
|
Contributor
There was a problem hiding this comment. nit: A better description would be |
||
| "allOf": [ | ||
| { | ||
| "$ref": "#/definitions/DeviceLifeCycleEventProperties" | ||
| } | ||
| ], | ||
| "properties": {} | ||
| }, | ||
| "IotHubDeviceDeletedEventData": { | ||
| "description": "Schema of the Data property of an EventGridEvent for a Microsoft.Devices.DeviceDeleted event.", | ||
| "allOf": [ | ||
| { | ||
| "$ref": "#/definitions/DeviceLifeCycleEventProperties" | ||
| } | ||
| ], | ||
| "properties": {} | ||
| }, | ||
| "DeviceLifeCycleEventProperties": { | ||
| "type": "object", | ||
| "description": "Schema of the Data property of an EventGridEvent for a device life cycle event (DeviceCreated, DeviceDeleted).", | ||
| "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": { | ||
| "description": "Information about the device twin, which is the cloud represenation of application device metadata.", | ||
| "$ref" : "#/definitions/DeviceTwinInfo" | ||
| } | ||
| } | ||
| }, | ||
| "DeviceTwinInfo": { | ||
| "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": { | ||
|
Contributor
There was a problem hiding this comment. As before, please do not define inline properties like so, create a new definition |
||
| "desired": { | ||
| "description": "A portion of the properties that can be written only by the application back-end, and read by the device.", | ||
| "$ref" : "#/definitions/DeviceTwinProperties" | ||
| }, | ||
| "reported": { | ||
| "description": "A portion of the properties that can be written only by the device, and read by the application back-end.", | ||
| "$ref" : "#/definitions/DeviceTwinProperties" | ||
| } | ||
| } | ||
| }, | ||
| "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." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "DeviceTwinProperties": { | ||
|
Contributor
There was a problem hiding this comment. nit: Use a more meaningful name here, there already exists a definition for
Contributor
Author
There was a problem hiding this comment. in this context reported properties has a different meaning. So using that would only confuse the reader who understands the iot hub twin concepts. DeviceTwinProperty is the right name. Also, TwinInfo and TwinProperties were names I picked from another swagger doc that a partner team of us already uses. I would like to be consistent with those. I will pass on this nit. |
||
| "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": { | ||
| "description": "Metadata information for the properties JSON document.", | ||
| "$ref" : "#/definitions/DeviceTwinMetadata" | ||
| }, | ||
| "$version": { | ||
| "type": "number", | ||
| "description": "Version of device twin properties." | ||
| } | ||
| } | ||
| }, | ||
| "DeviceTwinMetadata" : { | ||
| "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." | ||
| } | ||
| } | ||
| } | ||
| } | ||
| } | ||
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.