alexa技能个数

by Garrett Vargas

通过Garrett Vargas

如何在您的技能中使用Alexa演示语言 (How to use Alexa Presentation Language in your skill)

Amazon recently released the Alexa Presentation Language (APL). APL provides a richer display for multimodal skills. It is based on modern frameworks that separate display elements from data sources. It gives you the flexibility to include many visual elements such as graphics, images, and slideshows and lets you tailor the display for different devices.

亚马逊最近发布了Alexa Presentation Language(APL)。 APL为多模式技能提供了更丰富的展示。 它基于将显示元素与数据源分开的现代框架。 它使您可以灵活地包含许多视觉元素，例如图形，图像和幻灯片，并可以针对不同设备定制显示。

In this article, I’m going to walk through how I updated one of my skills to use APL. You can also use these tips and techniques if you are creating a new skill.

在本文中，我将逐步讲解如何更新一项技能以使用APL。 如果您要创建新技能，也可以使用这些技巧和技巧。

Most of my skills feature multimodal support using the Display Interface. I decided to learn APL by updating one of my existing skills. I focused on my Video Poker skill because I wasn’t happy with the existing customer experience.

我的大部分技能都使用显示界面提供多模式支持。 我决定通过更新现有技能之一来学习APL。 我专注于我的视频扑克技能，因为我对现有的客户体验不满意。

Video Poker presents users with a 5-card poker hand, with an ability to hold and discard cards before drawing to complete a hand. Users can do this by voice command (“keep the first card” or “keep the pair of jacks”), or by touching cards on a visual display. ListTemplate2 was the best way to do this with the Display Interface. However, this came with the limitation of only allowing three cards on the screen at a time and putting numbers beneath each card in the list.

Video Poker向用户展示了五张纸牌的扑克牌，并且能够在抽签完成之前握住和丢弃纸牌。 用户可以通过语音命令(“保留第一张卡”或“保留一对插Kong”)或触摸可视显示器上的卡来执行此操作。 ListTemplate2是使用显示界面执行此操作的最佳方法。 但是，这样做的局限性是一次只能在屏幕上显示三张卡片，并将数字放在列表中每张卡片的下方。

Using APL, I modified a ListTemplate2 layout to shrink the size of list items, reduce the spacing between them, and fit a full five card hand on the screen. I was able to remove the numbers from items in the list and put text indicating which held cards in a bold, red font. I was able to optimize the layout for different screen dimensions, such as smaller displays like the Echo Spot.

使用APL，我修改了ListTemplate2布局以缩小列表项的大小，减小它们之间的间距，并在屏幕上放满五张卡片。 我能够从列表中的项目中删除数字，并以粗体红色字体显示指示哪些卡的文本。 我能够针对不同的屏幕尺寸优化布局，例如像Echo Spot这样的小型显示器。

APL创作工具 (APL Authoring Tool)

The way I did this was through the APL Authoring Tool. This handy tool provides a list of different visual designs you can use as a baseline to create compelling visuals for your skill. It also allows you to save and upload layouts, so you can extract them to your skill code, or upload them if you make offline updates. For this use case, I started with the Image Forward List Sample, which is based on ListTemplate2.

我这样做的方法是通过APL创作工具 。 这个方便的工具提供了一系列不同的视觉设计，您可以将它们用作基线来创建具有吸引力的视觉效果。 它还允许您保存和上载布局，因此您可以将其提取到技能代码中，或者在进行离线更新时上载它们。 对于此用例，我从基于ListTemplate2的Image Forward List Sample开始。

Once you select this visual design in the tool, you’ll see a generic example of a list with cheese samples. You’ll see the APL document at the bottom of the screen separated into two tabs:

在工具中选择此视觉设计后，您将看到包含奶酪样品的清单的一般示例。 您将在屏幕底部看到APL文档，该文档分为两个选项卡：

• “Image Forward List Sample” which provides the layout
  提供布局的“图像转发列表样本”
• “Data JSON” tab which provides a view of the document data.
  “数据JSON”选项卡提供了文档数据的视图。

Take a moment to look through the JSON on both the Image Forward List Sample tab (the layout code) and the Data JSON tab (the content code). You’ll notice in the layout that there are several references to values enclosed in ${} such as ${payload.listTemplate2ListData.listPage.listItems.length}. If you look in the content file, you’ll see that this is a path to a value within the content. This is how APL binds data to the presentation layer and lets you make changes.

花一点时间浏览“图像转发列表样本”选项卡(布局代码)和“数据JSON”选项卡(内容代码)上的JSON。 您会在布局中注意到，对${}包含的值有多个引用，例如${payload.listTemplate2ListData.listPage.listItems.length} 。 如果查看内容文件，您会看到这是内容中值的路径。 这就是APL将数据绑定到表示层并进行更改的方式。

更新数据源 (Updating Data Sources)

As a first step, I wanted to update the data so it would show card images and text relevant to my skill. That way, as I started to update the layout itself, I would be able to see how it would look with my actual images. The Authoring Tool shows your rendered screen images in real time, making it convenient to use as you attempt to perfect your layout. To update the data, I took the following steps:

第一步，我想更新数据，以便显示与我的技能有关的卡片图像和文本。 这样，当我开始更新布局本身时，我将能够看到它与实际图像的外观。 创作工具实时显示您渲染的屏幕图像，使您在尝试完善布局时使用起来非常方便。 要更新数据，我采取了以下步骤：

• Click on the Data JSON tab
  单击数据JSON选项卡

• In the listTemplate2Metadata, change the title and logo elements to something relevant to Video Poker

  在listTemplate2Metadata ，将title和logo元素更改为与Video Poker相关的内容

• In this same element, change the url in the backgroundImages.sources fields to point to the background image I wanted to use

  在同一元素中，更改backgroundImages.sources字段中的url以指向我要使用的背景图像

• In listTemplate2ListData.listPage, I updated each of the items in the listItems array. Specifically, I updated this array to have 5 items (my cards), with listItemIdentifier and token set to “card.x” (where x ranged from 0–4). I removed the secondaryText since I only wanted one row of text (which would either be blank or say “HELD”). I updated the image.sources to point to URLs containing my card images. For now, I just selected some card images at random — my skill’s code will update the data during gameplay with the actual user’s hand

  在listTemplate2ListData.listPage ，我更新了listItems数组中的每个项目。 具体来说，我将该数组更新为5个项目(我的卡片)，并将listItemIdentifier和token设置为“ card.x”(其中x的范围为0–4)。 我删除了secondaryText因为我只想要一行文本(可以为空白或说“ HELD”)。 我更新了image.sources以指向包含我的卡片图像的URL。 现在，我只是随机选择了一些卡片图像-我的技能代码将在游戏过程中使用实际用户的手来更新数据

• Update the hint text to use a transformation. Rather than hard-coding the hint string with the Alexa keyword, you can use a transform to change a hint into one that uses the wake word associated with the device, in case the user has changed it. You do this by removing the hintText from listTemplate2ListData and adding the following into your lastTemplate2Metadata:

  更新提示文本以使用转换。 您可以使用转换将提示更改为使用与设备关联的唤醒字的提示，而不用用Alexa关键字对提示字符串进行硬编码，以防用户更改了提示。 您可以通过去除做到这一点hintText从listTemplate2ListData并添加以下到您的lastTemplate2Metadata：

"properties": {    "hintText": "select number 1"},"transformers": [    {        "inputPath": "hintText",        "transformer": "textToHint"    }],

Once I had made these to the data sources, my image looked like this — pretty similar to the skill as it exists with the ListTemplate2 display which makes sense since at this point I’m still using the layout based on ListTemplate2 and have only made content changes.

一旦将这些设置为数据源，我的图像就会看起来像这样–与ListTemplate2显示器所具有的技能非常相似，这很有意义，因为在这一点上我仍在使用基于ListTemplate2的布局，并且仅使内容变化。

更新布局 (Updating the Layout)

Now for the fun part — updating the layout to get five images on the screen at one time. For this part, I made updates to the layout on the “Image Forward List Sample” tab. To make these changes, I clicked on the slider that lets you switch between a visual view of nested APL components to a raw JSON view. I find viewing the full document JSON easier to consume than clicking on each component and editing the JSON within the component. But you can play with it and follow whichever approach seems most natural to you.

现在开始有趣的部分-更新布局以一次在屏幕上获得五张图像。 对于这一部分，我对“图像转发列表样本”选项卡上的布局进行了更新。 要进行这些更改，我单击了滑块，使您可以在嵌套APL组件的可视视图与原始JSON视图之间切换。 我发现查看完整文档JSON比单击每个组件并在该组件内编辑JSON更容易使用。 但是您可以使用它，并按照您认为最自然的方法进行操作。

Before talking through the changes I made, I wanted to point out some of the elements of this layout template:

在讨论所做的更改之前，我想指出此布局模板的一些元素：

• There is a ListTemplate2 node in the JSON which provides two containers in an items node— one that applies to circular screens (like the Echo Spot) and the other for other screen types. In this blog, I’m going to focus on the non-Spot displays, but you should appreciate that you can also make changes specific to different screen layouts.

  有一个ListTemplate2其中提供两个容器在所述JSON节点items节点-一个适用于圆形筛(如回声景点)，另一个用于其他类型的屏幕。 在此博客中，我将重点介绍非点显示，但是您应该理解，您还可以针对不同的屏幕布局进行更改。

• Looking at the second container that we’ll be changing, you‘ll see a set of items including an Image (the background image), an AlexaHeader (the title on the screen), a Sequence (which is the list of cards), and an AlexaFooter (the hint at the bottom of the screen)

  查看我们将要更改的第二个容器，您将看到一组items包括图像(背景图像)， AlexaHeader (屏幕上的标题)， 序列 (卡列表)，和AlexaFooter (屏幕底部的提示)

• You’ll see that the Sequence points to HorizontalListItem, which is another container in this JSON document. It contains items consisting of an Image and two Text elements (the primary text and the secondary text)

  您将看到Sequence指向HorizontalListItem ，这是此JSON文档中的另一个容器。 它包含由一个Image和两个Text元素(主要文本和次要文本)组成的项目

With this context in mind, I made the following changes to this document:

考虑到这种情况，我对该文档进行了以下更改：

• Within the HorizontalListItem, I changed the Image item dimensions — specifically I set height to 40vh and width to 17vw. This sets the height of each card to 40% of the viewport height, and the width to 17% of the viewport width.

  在HorizontalListItem ，我更改了Image项的尺寸-具体地说，将height设置为40vh，将width为17vw。 这会将每个卡的高度设置为视口高度的40％，并将宽度设置为视口宽度的17％。

• I then updated midWidth to 100. This makes the width of each list item smaller and allows the five card images to appear on the screen

  然后，我将midWidth更新为100。这使每个列表项的宽度变小，并允许五张卡片图像出现在屏幕上

• I changed paddingLeft and paddingRight to 6 to reduce the amount of space between elements

  我将paddingLeft和paddingRight更改为6以减少元素之间的空间

• I added paddingTop and set it to 100 to add some separation between the header and the card images

  我添加了paddingTop并将其设置为100以在标题和卡片图像之间添加一些分隔

• I got rid of the secondary Text element since I don’t have two lines of text on my display
  我没有第二个Text元素，因为我的显示屏上没有两行文本

• I changed the primary Text element so it doesn’t draw the ordinal. So text in this element changed from <b>${ordinal}.</b>${data.textContent.priamryText.text} to <b>${data.textContent.primaryText.text}</b>.

  我更改了主要的Text元素，因此它不会绘制序数。 因此，此元素中的text从<b>${ordinal}.</b>${data.textContent.priam ryTe xt.text} to <b>${data.textContent.pri maryText.text} </ b> 。

• Within this same element, I wanted the text to be red and centered. I achieved this by adding a textAlign field with a value of “center,” and a color field with a value of “red.”

  在同一元素内，我希望文本为红色且居中。 我通过添加值为“ center”的textAlign字段和值为“ red”的color字段来实现此目的。

• In order to get the hint text from the appropriate location (now part of the metadata rather than the list data), I needed to update the AlexaFooter element to get the hint from ${payload.listTemplate2Metadata.properties.hintText}

  为了从适当的位置(现在是元数据的一部分而不是列表数据的位置)获取提示文本，我需要更新AlexaFooter元素以从${payload.listTemplate2Metadata.properties.hintText}获取提示。

Finally, I needed to make the cards in my list selectable, so I could respond when the user touches one of them on the screen. To do this, I needed to change the items that were associated with the Sequence element from a FullHorizontalListItem to a TouchWrapper which in turn contained a FullHorizontalListItem. In code, that means that I changed this:

最后，我需要将列表中的卡设为可选，以便当用户触摸屏幕上的其中一张卡时可以做出响应。 为此，我需要将与Sequence元素关联的项目从FullHorizontalListItem更改为TouchWrapper ，后者又包含FullHorizontalListItem 。 在代码中，这意味着我更改了此代码：

"item": [  {    "type": "FullHorizontalListItem",    "listLength": "${payload.listTemplate2ListData.listPage.listItems.length}"  }]

to this:

对此：

"item": [  {    "type": "TouchWrapper",    "onPress": {      "type": "SendEvent",      "arguments": [        "${data.token}"      ]    },    "item": {      "type": "FullHorizontalListItem",      "listLength": "${payload.listTemplate2ListData.listPage.listItems.length}"    }  }]

Note the onPress element in this item. Specifically, the list of arguments. You can specify an array of different arguments to send to your skill when an item is selected. Because my existing code was processing the token of the selected card, I decided to continue to do the same to minimize the amount of code I needed to change. But you could also pass in ${ordinal} which would tell you the index of the selected item without having to process the token.

请注意此项中的onPress元素。 具体来说，是参数列表。 您可以指定一组不同的参数，以在选择某项时发送给您的技能。 因为我现有的代码正在处理所选卡的令牌，所以我决定继续执行相同的操作，以最大程度地减少需要更改的代码量。 但是，您也可以传入${ordinal} ，它可以告诉您所选项目的索引，而无需处理令牌。

技能代码更新 (Updates to the Skill Code)

Once you’ve made changes within the Authoring Tool, you can select the Export Code button which will package up your layout and data files into one JSON file for you. I chose to use two different JSON files in my code, one called main which I used for the layout and another called datasources which I used for the data. I like keeping the separation of layout and content in my source code as a general best practice. It was surprising that Amazon’s Authoring Tool didn’t encourage this too.

在创作工具中进行更改后，可以选择“导出代码”按钮，它将为您将布局和数据文件打包为一个JSON文件。 我选择在代码中使用两个不同的JSON文件，一个称为main，用于布局，另一个称为数据源，用于数据。 我喜欢将布局和内容分离在源代码中，这是一般的最佳做法。 令人惊讶的是，亚马逊的创作工具也没有鼓励这样做。

Now that we’ve downloaded the document and content, we need to make code changes to incorporate it and update the data as the user plays with our skill. We can do this by manipulating data elements and then passing them back to the skill. I used Alexa’s response interceptor functionality (which I talk about in a separate blog post). I load the data source in from a JSON file, then update the cards and text within the structure before sending it off to Alexa. I do that with the following code:

现在，我们已经下载了文档和内容，我们需要进行代码更改以将其合并并在用户使用我们的技能进行更新时更新数据。 我们可以通过处理数据元素，然后将其传递回技能来做到这一点。 我使用了Alexa的响应拦截器功能(我在另一篇博客文章中谈到)。 我从JSON文件加载数据源，然后更新结构中的卡和文本，然后将其发送给Alexa。 我使用以下代码进行操作：

const main = require('./main.json');const datasource = require('./datasource.json');

function drawTable(handlerInput) {  const event = handlerInput.requestEnvelope;  const attributes = handlerInput.attributesManager.getSessionAttributes();  const game = attributes[attributes.currentGame];  let i;  let cardText;  let url;

// Update the images  for (i = 0; i < game.cards.length; i++) {    const card = game.cards[i];    url = GetCardURL(card);    cardText = (card.hold) ? 'HELD' : '';    datasource.listTemplate2ListData.listPage.listItems[i]      .textContent.primaryText.text = cardText;    datasource.listTemplate2ListData.listPage.listItems[i]      .image.sources[0].url = url;    datasource.listTemplate2ListData.listPage.listItems[i]      .image.sources[1].url = url;  }  // Give an appropriate hint  if (game.state === 'FIRSTDEAL') {      if (game.cards[0].hold) {        datasource.listTemplate2ListData.hintText = 'discard the first card';      } else {        datasource.listTemplate2ListData.hintText = 'hold the first card';      }      datasource.listTemplate2Metadata.title = 'Select cards to hold or say Deal';    } else {      datasource.listTemplate2ListData.hintText = 'deal';      datasource.listTemplate2Metadata.title = 'Your last hand';    }  }  return handlerInput.responseBuilder    .addDirective({      type: 'Alexa.Presentation.APL.RenderDocument',      version: '1.0',      document: main,      datasources: datasource,    });}

The second place I had to make a code change was to handle the user touching one of the items in my list. In my old code, I was parsing item tokens of the form “card.x” where x is the ordinal position of the card in the list. With a Display Interface, this meant looking for an ElementSelected request. In APL, your code will receive an APL.Presentation.APL.UserEvent, and you can process the request as follows to determine which card was selected:

我必须进行代码更改的第二个地方是让用户触摸列表中的一项。 在我的旧代码中，我正在解析形式为“ card.x”的项目令牌，其中x是列表中卡的顺序位置。 对于显示界面，这意味着寻找ElementSelected请求。 在APL中，您的代码将收到APL.Presentation.APL.UserEvent ，您可以按以下方式处理请求，以确定选择了哪张卡：

module.exports = {  canHandle(handlerInput) {    const request = handlerInput.requestEnvelope.request;       // Was this a touch item selected?    if (request.type === 'Alexa.Presentation.APL.UserEvent') {      return ((request.source.type === 'TouchWrapper')        && (request.source.handler === 'Press'));    }    return false;  },  handle(handlerInput) {    let index;    const event = handlerInput.requestEnvelope;    // Was this a touch item selected?    if (event.request.type === 'Alexa.Presentation.APL.UserEvent') {      const cards = event.request.arguments[0].split('.');      if (cards.length === 2) {        index = cards[1];      }            // Do something with the selected card...

}  },};

With these changes, I had a much cleaner looking Video Poker skill, which is sure to delight my customers more than the older format I was using. I’ve just started scratching the surface in terms of APL’s capabilities. But I can tell it will open up a new world of possibilities for voice-driven multimodal skills! Let me know in the comments about your own learnings with this new framework.

进行了这些更改之后，我的视频扑克技能变得更加清晰，这肯定会让我的客户满意，而我使用的是较旧的格式。 我才刚刚开始了解APL的功能。 但我可以说，这将为语音驱动多模式技能开辟新的可能性！ 在评论中让我知道您对这个新框架的了解。

翻译自: https://www.freecodecamp.org/news/how-to-use-alexa-presentation-language-in-your-skill-3c49961825c5/

alexa技能个数