Grato por sua visita. Neste momento esta página está apenas disponível em inglês.

APL Data Sources and Transformers

A data source defines a source of data that can be bound to an APL document. When a skill developer sends an APL document to Alexa, it can be accompanied by one or more data sources. The data sources are bound by name into the APL document's parameters. APL components within the document can then reference those data sources using a ${..} style APL data-binding expression.

Data sources exist inside a datasources object that is part of a RenderDocument directive, but outside of the APL document itself. This datasources object can only contain other objects (the actual data sources). To access a datasource, the APL document's mainTemplate declares a parameter called payload that points at the root datasources object. The following response demonstrates an APL document that binds to a single data source called myDocumentData. The data source name is chosen by the developer, but this same name must be used when binding to properties of the data source from within the APL document.

{
  "version": "1.0",
  "response": {
    "outputSpeech": {
      "type": "SSML",
      "ssml": "<speak>This is a sample</speak>"
    },
    "directives": [
      {
        "type": "Alexa.Presentation.APL.RenderDocument",
        "token": "[SkillProvidedToken]",
        "document": {
          "type": "APL",
          "version": "1.0",
          "theme": "auto",
          "import": [
            {
              "name": "alexa-layouts",
              "version": "1.0.0"
            }
          ],
          "resources": [
            {
              "description": "Stock color for the light theme",
              "colors": {
                "colorTextPrimary": "#151920"
              }
            },
            {
              "description": "Stock color for the dark theme",
              "when": "${viewport.theme == 'dark'}",
              "colors": {
                "colorTextPrimary": "#f0f1ef"
              }
            }
            ],
          "styles": {
            "textStyleBase": {
              "description": "Base font description; set color and core font family",
              "values": [
                {
                  "color": "@colorTextPrimary",
                  "fontFamily": "Amazon Ember Display"
                }
              ]
            }
          },
          "layouts": {},
          "mainTemplate": {
            "parameters": [
              "payload"
            ],
            "items": [
              {
                "type": "Container",
                "direction": "column",
                "width": "100vw",
                "height": "100vh",
                "items": [
                  {
                    "type": "Text",
                    "text": "${payload.myDocumentData.title}"
                  }
                ]
              }
            ]
          }
        },
        "datasources": {
          "myDocumentData": {
            "title": "This is a very simple sample"
          }
        }
      }
    ]
  },
  "userAgent": "ask-node/2.0.7 Node/v6.10.3",
  "sessionAttributes": {}
}

Object type data sources

APL also supports data sources with a type of object. Unlike untyped data sources, typed data sources prescribe a structure that can be used to enable additional functionality like the transformation of data source values. The following shows the properties applicable to an object data source. The object type data source enables skills developers to use transformers which in turn can be used to do things like add hints to APL documents or convert SSML expressions to speech for use with the [SpeakItem command]. See Transformers.

Property Type Required Description
type object Yes Must be "object".
properties object No An object containing bindable properties that can be used with transformers.
objectID String No An optional identifier for an object data source.
description String No Optional description of the data source.
transformers Array No An array of transformers that will be applied to values in the properties object.

The code below shows an object data source with an ssmlToSpeech transformer. Note that a skill developer would also have to issue a SpeakItem command to make Alexa to play the speech associated with the Text component.

Data source types

The following types of data sources are currently supported:

  • Object: A single fixed JSON object.

The type property of the data source is used to distinguish between data sources types.

Object data source

An object data source is a simple JSON object of static data. The JSON data is fixed and will not be changed by the server. The properties for the object data source are as follows:

Property Type Required Description
description String No Optional description of the data source.
objectID String No An optional identifier for an object data source
properties Map Yes A collection of bindable properties that make up the data source. This is an embedded JSON object.
translators Array No Transformers
type object Yes Must be "object".

Here's an example of an object data source named "recipe". Note that the properties object may be arbitrarily complex.

{
  "datasources": {
    "recipe": {
      "type": "object",
      "properties": {
        "title": "Scottish Shortbread",
        "makes": "48 servings",
        "time": {
          "prep": "15 minutes",
          "bake": "20 minutes"
        },
        "ingredients": [
          "2 cups butter, softened",
          "1 cup packed brown sugar",
          "4 to 4 1/2 cups all-purpose flour"
        ]
      }
    }
  }
}

This object data source could be used in conjunction with an APL document like the following. Click the button to view the document.

See Transformers.

Transformers

Transformers transform data in a data source into alternative representations. The RenderDocument directive currently supports three transformers:

  • ssmlToSpeech: A transformer that converts plain text or Speech Synthesis Markup Language (SSML) into speech appropriate for binding with the speech property of an APL component. The speech associated with the component can then be spoken using a SpeakItem APL command. The use of the audio tag with the ssmlToSpeech transformer is not supported.

  • ssmlToText: A transformer that converts SSML to plain text.

  • textToHint: A transformer that adds the Alexa wake word (Alexa, Computer, Echo or Amazon) to convert text in to an Alexa hint string.

A transformer converts data from a named property inside a data source, performs the transformation and writes the data back to a property in the original data source. If the outputName is not supplied, a transformer overwrites the input property. All transformers have the base properties shown in this table:

Property Type Required Description
transformer String Yes The type of the transformer
inputPath String Yes Path within the object to the part to be translated
outputName String No Name of the property to be added to the object. If no outputName is supplied, the inputPath will be overwritten with the transformed output.

The inputPath may unambiguously reference a single entity in the source object, or may reference a set of entities using wildcard properties or unresolved arrays. Each property that matches the inputPath will be transformed. The inputPath pattern is a symbol followed by some number of node and/or wildcard references.

The following rules apply:

  • A symbol name or array index must match an existing object property or array index inside the properties block. If the match fails, the transformation is abandoned.

  • The location where the output is stored is found by replacing the last non-wildcard node with the outputName. If there are no non-wildcard nodes, the symbol is replaced by outputName.

  • The last non-wildcard node cannot be a numeric index. If the last non-wildcard node is numeric, the transformation is abandoned.

These examples demonstrate how referencing works. Consider the sample data shown here:

{
    "datasources": {
        "myDocumentData": {
            "type": "object",
            "properties": {
                "name": "Sam Lee",
                "address": {
                    "street": "301 Charles Way",
                    "city": "Bedford"
                },
                "family": [
                    { "name": "Alex", "relation": "wife" },
                    { "name": "Patty", "relation": "daughter" }
                ],
                "contacts": [ "Robin Barnes", "Betty Barnes" ]
            },
            "transformers": [
            {
                "inputPath": [See Table Below],
                "outputName": [See Table Below],
                "transformer": "ssmlToSpeech"
            }
            ]
        }
    }
}
inputPath Item to be transformed Result stored at:
name "Sam Lee" outputName
address.street "301 Charles Way" address.outputName
contacts.* ["Robin Barnes", "Betty Barnes"] outputName[0], outputName[1]
family[0].name "Alex" family[0].outputName
family[*].name "Alex", "Patty" family[0].outputName, family[1].outputName
address.* "301 Charles Way", "Bedford" outputName.street, outputName.city

The following do not work:

  • family[3].name – Does not work - See rule #1

  • family[1].names – Does not work - See rule #1

  • family[0] { "name": "Alex", "relation": "wife" } Does not work - see rule #3

ssmlToSpeech Transformer

The SSML to speech transformer converts an SSML string into a speakable entity. The SSML to speech transformer has the properties shown in this table:

Property Type Required Description
transformer ssmlToSpeech Yes The name of the transformer
inputPath String Yes Path within the object to the part to be transformed
outputName String Yes Name of the property to be added to the object

The output from the SSML to speech transformer should be attached to the speech property of a component. The code below shows a version of a "Cat Facts" skill that associates speech with a Text component bound to the cat fact.

{
    "type": "Container",
    "item": {
        "type": "Text",
        "id": "catFactText",
        "text": "${payload.catFactData.properties.catFact}",
        "speech": "${payload.catFactData.properties.catFactSpeech}"
    }
 }

Next, the code below shows the corresponding object data source and transformers you should send as part of your skill request.

{
    "datasources": {
            "catFactData": {
                "type": "object",
                "properties": {
                    "backgroundImage": "https://.../catfacts.png",
                    "title": "Cat Fact #9",
                    "logoUrl": "https://.../logo.png",
                    "image": "https://.../catfact9.png",
                    "catFactSsml": "<speak>Not all cats like <emphasis level='strong'>catnip</emphasis>.</speak>"
                },
                "transformers": [
                    {
                      "inputPath": "catFactSsml",
                      "outputName": "catFactSpeech",
                      "transformer": "ssmlToSpeech"
                    },
                    {
                      "inputPath": "catFactSsml",
                      "outputName": "catFact",
                      "transformer": "ssmlToText"
                    }
                ]
            }
    }
 }

Finally, to read the cat fact, you must use the Alexa.Presentation.APL.ExecuteCommands directive with the SpeakItem command. The code below shows the Alexa.Presentation.APL.ExecuteCommands directive you can use to read the cat fact. Note that the token supplied in the ExecuteCommands directive is required and must match the token provided by the skill in the RenderDocument directive used to render the APL document.

{
    "type" : "Alexa.Presentation.APL.ExecuteCommands",
    "token": "[SkillProvidedToken]",
    "commands": [{
        "type": "SpeakItem",
        "componentId" : "catFactText",
        "highlightMode": "line",
        "align": "center"
    }]
 }

ssmlToText Transformer

The SSML to text transformer converts a full SSML text string into text that is more appropriate for human reading by removing the SSML markup. It has the same properties as the ssmlToSpeech transformer except the transformer value must be set to ssmlToText.

textToHint Transformer

Skill developers can use the textToHint transformer to automatically add the correct wake word to a hint string shown in an APL document instead of guessing the device wake word or defaulting to "Alexa". The textToHint transformer is applied to a property on a data source of type object that binds to the AlexaFooter layout. This table shows the properties applicable to a textToHint transformer.

Property Type Required Description
transformer textToHint Yes This property must be set to textToHint to invoke the text to hint transformer.
inputPath string Yes The path of the data source value that needs to be transformed.
outputName string No The name of the data source property where the transformed output will be stored. This output property will always be a sibling of the input property. If an outputName isn't provided the value in the inputPath will be replaced with the output of the transformer.

To present a hint, import the alexa-layouts package into the APL document and then use the AlexaFooter layout that is part of the package in the APL document. The following code sample shows an APL document that uses an AlexaFooter layout to present the hint. Note how AlexaFooter's footerHint property is bound to a property of the catFactData data source.

{
    "type": "APL",
    "version": "1.0",
    "import": [{
        "name": "alexa-layouts",
        "version": "1.0.0"
    }],
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "items": [
                    {
                        "type": "AlexaHeader",
                        "title": "${payload.catFactData.properties.title}",
                        "attributionImage": "${payload.catFactData.properties.logoUrl}"
                    }
                ]
            },
            {
                "type": "ScrollView",
                "item": {
                    "type": "Text",
                    "id": "catFactText",
                    "text": "${payload.catFactData.properties.catFact}"
                }
            },
        {
            "type": "AlexaFooter",
            "footerHint": "${payload.catFactData.properties.hintString}"
        }
      ]    
    }
 }

The following code illustrates how skill developers can bind data sources to the footerHint to their AlexaFooter. Using catFactData as an example, the catFactData data source contains a textToHint transformer which is applied to the hintString property of the data source. Note that in order to use the transformer, the properties to be transformed must be placed in a properties object inside the object data source. This transformer will transform hintString into a Try "Alexa,… -style hint that can be presented to the end user.

{
    "datasources": {
        "catFactData": {
            "type": "object",
            "properties": {
                "title": "Cat Fact #9",
                "logoUrl": "https://.../logo.png",
                "catFact": "Not all cats like catnip.",
                "hintString": "show me a persian cat fact"
            },
            "transformers": [
                {
                  "inputPath": "hintString",
                  "transformer": "textToHint"
                }
            ]
        }
    }
 }