Alexa.DataController Interface 1.0
Implement the Alexa.DataController
interface in your Alexa skill to enable users to view and delete data on Alexa, on the device, and in the device cloud. When the customer asks Alexa to view or delete data, your skill receives a data controller directive. When the customer deletes data directly on the device or device app, your skill sends the data controller events to Alexa. The Alexa.DataController
interface is a generic controller interface.
Typically, you use the Alexa.DataController
interface with the Alexa.SmartVision.ObjectDetectionSensor
interface.
For the list of languages that the Alexa.DataController
interface supports, see List of Alexa Interfaces and Supported Languages. For the definitions of the message properties, see Alexa Interface Message and Property Reference.
Data retrieval
Alexa initiates data retrieval by sending a directive to your skill. After your skill reports the requested data, Alexa might display the data to the customer in the Alexa app. Also, you can report the data proactively by sending an event to Alexa.
The following example shows the message flow when Alexa requests data from your skill. The nextToken
parameter in the DataReport
event indicates that there are multiple results. To get the next results, Alexa sends another ReportData
directive with a matching nextToken
.
Utterances
The Alexa.DataController
interface doesn't have any user utterances. Instead, Alexa communicates with your skill after the customer requests to view and delete data from the Alexa app.
Properties and objects
The Alexa.DataController
interface defines the following properties and objects.
Reportable properties
The Alexa.DataController
interface doesn't include any reportable properties.
DataRetrievalSchema object
The DataRetrievalSchema
object defines the data format and name of the schema for the data published in the DataReport
event.
Property | Description | Type |
---|---|---|
|
Data format. |
String |
|
Name of the data schema. |
String |
Query object
The Query
object defines the query string for the ReportData
and DeleteData
directives. All properties are optional.
Property | Description | Type |
---|---|---|
|
Unique identifiers for query by identifier. |
Array of string |
|
Beginning time for query by timestamp range. |
|
|
End time for query by timestamp range. |
|
Discovery
You describe endpoints that support Alexa.DataController
by using the standard discovery mechanism described in Alexa.Discovery
.
Alexa.DataController
interface doesn't have any controllable properties.To let Alexa know the health of your device, also implement the Alexa.EndpointHealth
interface.
Capabilities object
An endpoint can support multiple data controllers, so you must always include the instance
name in your events and responses. Define an instance
for each interface and schema that the same endpoint supports in the capabilities
object.
The following example shows a data controller instance.
{
"type": "AlexaInterface",
"interface": "Alexa.DataController",
"instance": "DataController-SmartVisionData",
"version": "1.0"
}
Configuration object
In addition to the usual discovery response fields, for Alexa.DataController
, include a configuration
object that contains the following fields.
Property | Description | Type | Required |
---|---|---|---|
|
Alexa interface that this controller applies to. |
String |
Yes |
|
Version of the Alexa interface that this controller applies to. |
String |
Yes |
|
Indicates that the |
|
No |
|
Indicates the search methods supported for data access. |
Array of strings |
Yes |
Discover response example
The following example shows a Discover.Response
message for a smart-vision camera that supports the Alexa.DataController
and Alexa.SmartVision.ObjectDetectionSensor
interfaces.
{
"event": {
"header": {
"namespace": "Alexa.Discovery",
"name": "Discover.Response",
"payloadVersion": "3",
"messageId": "Unique identifier, preferably a version 4 UUID"
},
"payload": {
"endpoints": [{
"endpointId": "Unique ID of the endpoint",
"manufacturerName": "Sample Manufacturer",
"description": "Description that appears in the Alexa app",
"friendlyName": "Your device name, displayed in the Alexa app",
"displayCategories": ["CAMERA"],
"additionalAttributes": {
"manufacturer": "Sample Manufacturer",
"model": "Sample Model",
"serialNumber": "Serial number of the device",
"firmwareVersion": "Firmware version of the device",
"softwareVersion": "Software version of the device",
"customIdentifier": "Optional custom identifier for the device"
},
"cookie": {},
"capabilities": [{
"type": "AlexaInterface",
"interface": "Alexa.DataController",
"instance": "DataController-SmartVisionData",
"version": "1.0",
"properties": {},
"configuration": {
"targetCapability": {
"name": "Alexa.SmartVision.ObjectDetectionSensor",
"version": "1.0"
},
"dataRetrievalSchema": {
"type": "JSON",
"schema": "SmartVisionData"
},
"supportedAccess": ["BY_IDENTIFIER", "BY_TIMESTAMP_RANGE"]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.SmartVision.ObjectDetectionSensor",
"version": "1.0",
"properties": {
"supported": [{
"name": "objectDetectionClasses"
}],
"proactivelyReported": true,
"retrievable": true
},
"configuration": {
"objectDetectionConfiguration": [{
"imageNetClass": "person"
},
{
"imageNetClass": "package",
"isAvailable": false,
"unavailabilityReason": "SUBSCRIPTION_REQUIRED"
}
]
}
},
{
"type": "AlexaInterface",
"interface": "Alexa.EndpointHealth",
"version": "3",
"properties": {
"supported": [{
"name": "connectivity"
}],
"proactivelyReported": true,
"retrievable": true
}
},
{
"type": "AlexaInterface",
"interface": "Alexa",
"version": "3"
}
]
}]
}
}
}
Directives and events
The Alexa.DataController
interface defines the following directives and events.
ReportData directive
Support the ReportData
directive so that a customer can request to view data stored on your endpoint.
ReportData directive example
The following example shows a ReportData
directive that Alexa sends to a smart-vision camera skill to retrieve data by identifier. The directive doesn't include the token because Alexa requests the first page of data.
{
"directive": {
"header": {
"namespace": "Alexa.DataController",
"name": "ReportData",
"payloadVersion": "1.0",
"instance": "DataController-SmartVisionData",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"queryType": "QUERY_BY_IDENTIFIER",
"query": {
"ids": ["unique data identifier"]
},
"maxResults": 1
}
}
}
ReportData directive payload
The following table shows the payload details for the ReportData
directive.
Property | Description | Type | Required |
---|---|---|---|
|
Identifies how to search the data. |
String |
Yes |
|
Identifies the search string based on the specified |
Query object |
No |
|
Specifies the maximum number of matching results to return. |
Integer |
Yes |
|
Token to use to retrieve a specific page of the results. If the token isn't included, the response contains the first page of the matching results. |
String |
No |
ReportData response
If you handle a ReportData
directive successfully, respond with a DataReport
event. Include the data in the response.
ReportData directive error handling
If you can't handle a ReportData
directive successfully, respond with an Alexa.DataController.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event.
DeleteData directive
Support the DeleteData
directive so that a customer can request to delete data from your endpoint.
DeleteData directive example
The following example shows a DeleteData
directive that Alexa sends to a smart-vision camera skill to delete data by time range.
{
"directive": {
"header": {
"namespace": "Alexa.DataController",
"name": "DeleteData",
"payloadVersion": "1.0",
"instance": "DataController-SmartVisionData",
"messageId": "Unique version 4 UUID",
"correlationToken": "Opaque correlation token"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "OAuth2 bearer token"
},
"endpointId": "endpoint id",
"cookie": {}
},
"payload": {
"queryType": "QUERY_BY_TIMESTAMP_RANGE",
"query": {
"fromTime": "2021-12-12T10:30:00:00Z",
"toTime": "2021-12-12T16:20:50:52Z"
}
}
}
}
DeleteData directive payload
The following table shows the payload details for the DeleteData
directive.
Property | Description | Type | Required |
---|---|---|---|
|
Identifies how to search the data. |
String |
Yes |
|
Identifies the search string based on the specified |
Query object |
No |
DeleteData response
If you handle a DeleteData
directive successfully, respond with an DataDeleted
event.
DeleteData directive error handling
If you can't handle a DeleteData
directive successfully, respond with an Alexa.DataController.ErrorResponse
event. You can also respond with a generic Alexa.ErrorResponse
event.
DataReport event
Send a DataReport
event to the Alexa event gateway to report data proactively to Alexa. For details, see Send Events to the Event Gateway. You can send the event at any time or in response to a ReportData
directive. Include the correlation token if you send the event in response to the directive. Otherwise, don't include the correlation token.
The event includes a token that indicates whether there is more data to retrieve. After Alexa receives a DataReport
event that includes a nextToken
parameter, Alexa sends a ReportData
directive with the same nextToken
value to your skill. In response, your skill must send the next set of data results in another DataReport
event.
DataReport event example
The following example shows a DataReport
event that a smart-vision camera skill sends to Alexa in response to a ReportData
directive. The example includes the correlationToken
.
{
"event": {
"header": {
"namespace": "Alexa.DataController",
"name": "DataReport",
"instance": "DataController-SmartVisionData",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "Opaque correlation token"
},
"endpointId": "endpoint id"
},
"payload": {
"paginationContext": {
"nextToken": "token1"
},
"dataSchema": {
"type": "JSON",
"schema": "SmartVisionData"
},
"data": [{
"eventIdentifier": "2b3409df-d686-4a52-9bba-d361860bac61",
"imageNetClass": "person",
"mediaId": "2c3409df-d686-4a52-9bba-d361860bac61",
"objectIdentifier": "4a3409df-d686-4a52-9bba-d361860bacbf",
"frameIndex": 2,
"frameWidthInPixels": 1980,
"frameHeightInPixels": 1080,
"frameImageUri": "https://example.com/frames/frame1.jpg",
"croppedImageUri": "https://example.com/images/image1.jpg"
},
{
"eventIdentifier": "2b3409df-d686-4a52-9bba-d361860bac62",
"imageNetClass": "package",
"mediaId": "2c3409df-d686-4a52-9bba-d361860bac62",
"objectIdentifier": "4a3409df-d686-4a52-9bba-d361860b4562",
"frameIndex": 5,
"frameWidthInPixels": 1980,
"frameHeightInPixels": 1080,
"frameImageUri": "https://example.com/frames/frame2.jpg",
"croppedImageUri": "https://example.com/images/image2.jpg"
}
]
}
}
}
DataReport event payload
The following table shows the payload details for the DataReport
event.
Property | Description | Type | Required |
---|---|---|---|
|
Information about the next page of results. If you don't support pagination, don't include this parameter. |
Object |
No |
|
Token used to report the next page of results. If there are more results, include this parameter. |
String |
No |
|
Schema of the included data. You identified the schema format in your discovery response. |
DataRetrievalSchema object |
No |
|
For JSON schemas, include the array of JSON data. For binary schemas, don't include this parameter and pass the data as a multi-part attachment. |
Array of String |
No |
DataReport response
If your skill proactively sent a DataReport
event and Alexa handles the event successfully, your skill receives HTTP status code 202 Success
. On error, Alexa sends the appropriate HTTP status code.
The following table shows the HTTP status codes sent in response to the event.
Status | Description |
---|---|
|
Operation succeeded. |
|
Indicates that the request is invalid or badly formatted. Verify the event payload and check for any missing or invalid fields. For example, the |
|
Indicates that the request didn't include the authorization token or the token is invalid or expired. |
|
Indicates that the authorization token doesn't have sufficient permissions or the skill is disabled. |
|
Indicates that the skill doesn't exist in the corresponding stage. |
|
Maximum number or size of a parameter exceeds the limit. For example, more than 50 identifiers are included in the |
|
Number of requests per minute is too high. Use exponential back-off and retry the request. |
|
An error occurred on the server. The skill can retry by using exponential back-off. |
|
Server is busy or unavailable. The skill can retry by using exponential back-off. |
DataDeleted event
Send a DataDeleted
event to the Alexa event gateway to notify Alexa proactively that you deleted the data identified by a unique identifier. For details, see Send Events to the Event Gateway. You can send the event at any time or in response to a DeleteData
directive. Include the correlation token if you send the event in response to the directive. Otherwise, don't include the correlation token.
DataDeleted event example
The following example shows a DataDeleted
event that a smart-vision camera skill sends to Alexa in response to a DeleteData
directive. Include the correlation token if you send the event in response to the directive. Otherwise, don't include the correlation token.
{
"event": {
"header": {
"namespace": "Alexa.DataController",
"name": "DataDeleted",
"instance": "DataController-SmartVisionData",
"messageId": "Unique identifier, preferably a version 4 UUID",
"correlationToken": "Opaque correlation token that matches the request",
"payloadVersion": "1.0"
},
"endpoint": {
"scope": {
"type": "BearerToken",
"token": "Opaque correlation token"
},
"endpointId": "endpoint id"
},
"payload": {
"queryType": "QUERY_BY_IDENTIFIER",
"query": {
"ids": ["2b3409df-d686-4a52-9bba-d361860bac61", "2b3409df-d686-4a52-9bba-d361860bac62"]
}
}
}
}
DataDeleted event payload
The following table shows the payload details for the DataDeleted
event.
Property | Description | Type | Required |
---|---|---|---|
|
Identifies how to search the data. |
String |
Yes |
|
Identifies the search string based on the specified |
Query object |
No |
DataDeleted response
If your skill proactively sent a DataDeleted
event and Alexa handles the event successfully, your skill receives HTTP status code 202 Success
. On error, Alexa sends the appropriate HTTP status code. If Alexa sent the DataDeleted
event to your skill proactively, respond with the appropriate HTTP status code.
The following table shows the HTTP status codes sent in response to the event.
Status | Description |
---|---|
|
Operation succeeded. |
|
Indicates that the request is invalid or badly formatted. Verify the event payload and check for any missing or invalid fields. For example, the |
|
Indicates that the request didn't include the authorization token or the token is invalid or expired. |
|
Indicates that the authorization token doesn't have sufficient permissions or the skill is disabled. |
|
Indicates that the skill doesn't exist in the corresponding stage. |
|
Maximum number or size of a parameter exceeds the limit. For example, more than 50 identifiers are included in the |
|
Number of requests per minute is too high. Use exponential back-off and retry the request. |
|
An error occurred on the server. The skill can retry by using exponential back-off. |
|
Server is busy or unavailable. The skill can retry by using exponential back-off. |
Change reporting
You send a ChangeReport
event to report changes proactively in the state of an endpoint. You identify the properties that you proactively report in your discovery response. For details about change reports, see Understand State and Change Reporting.
Alexa.DataController
interface doesn't define any proactively reportable properties. However, you send change reports for the other interfaces that you implement in your skill. Related topics
- Alexa.ModeController
- Alexa.RangeController
- Alexa.SimpleEventSource
- Alexa.ToggleController
- Works with Alexa certification
Last updated: Nov 22, 2023