フラッシュブリーフィングスキルAPIフィードのリファレンス



フラッシュブリーフィングスキルAPIフィードのリファレンス

このトピックでは、フラッシュブリーフィングスキルのフィードの要件とサポートされる形式について説明し、利用できる各形式の例を示します。各フラッシュブリーフィングスキルには、1つ以上のフィードがあります。フィードに利用できる形式は比較的単純ですが、サポートされる形式にはそれぞれ、いくつかの基本的な要件があります。

フィードの要件

フラッシュブリーフィングスキルの各フィードには、ユーザーに対してAlexaが読み上げるテキストコンテンツ、または再生するオーディオコンテンツのいずれかが含まれます。各フィードは以下の要件を満たす必要があります。

エンドポイントの要件

  • UTF-8でエンコードされていること。

  • パスワード保護されていないHTTPSエンドポイントであること。例:https://developer.amazon.com/public/community/blog/feed/flashbriefing.rss
  • 以下のいずれかの形式のコンテンツを提供すること。
    • JSON(推奨形式)
    • RSS(利用可)

形式の要件

以下は、基本的なフィード形式の要件です。詳細については、フィード形式の詳細を参照してください。

  • HTTP Content-Typeヘッダーでファイル形式をMIMEタイプとして指定すること。
  • 一度に1~5個の異なるフィード項目を提供できること。
    • これより多い項目が提供された場合、Alexaは最初の5個より後の項目を無視します。
    • 項目は、日付の新しいものから順に提示されます。古い項目は、Alexaで無視されることがあります。
    • フィード内の各項目は一意にする必要があります。別のフィード項目と重複することはできません。

オーディオコンテンツの要件

オーディオコンテンツのラウドネスを基準に合わせる方法の詳細については、オーディオコンテンツのラウドネス値の正規化を参照してください。

  • オーディオ項目にオーディオコンテンツへのHTTPS URLが含まれていること。ストリームURLの場合はHTTPSが必須です。
  • オーディオコンテンツが、256kbpsモノラル、またはステレオMP3で作成されていること。
  • コンテンツの長さが10分以内であること。
  • プログラムのラウドネス値が平均-14 dB LUFS/LKFSであること。
  • トゥルーピーク値が-2 dBFS以下であること。
  • -19 dB LUFS以上であること。
  • -9 dB LUFS以下であること。
  • トゥルーピークのガイドラインを超えないこと。

テキストコンテンツの要件

  • フィード項目の長さが4,500文字を超えないこと。4,500文字を超える場合は、4,500文字未満で、かつ4,500文字目にもっとも近くで終わる文章の次のコンテンツ以降が切り捨てられます。
  • SSML、HTML、XMLのタグなどの特殊文字を含まない、プレーンテキストであること。
  • 文章は、読み上げたときに簡単に理解できるよう、句読点で適切に区切られ、長すぎないこと。読点(、)があると短い休止が入ります。句点(。)、疑問符(?)、感嘆符(!)があると長い休止が入ります。標準以外の句読点では読み上げ機能(TTS)で問題が発生することがあるので、使用しないでください。

パフォーマンス要件

Alexaは15分ごとにコンテンツをキャッシュすることで、容量の大きいトラフィックにも対応できるようにしています。詳細については、パフォーマンスのヒントを参照してください。次の要件を満たしている必要があります。

  • フィードを24時間365日いつでも利用できること。計画停電の際には、Amazonに連絡してください(content-skill-submissions@amazon.com)。
  • エンドポイントで1分間に1つ以上のリクエストを処理できること。
  • 応答のレイテンシーが1秒未満であること。

フィードの更新

フラッシュブリーフィングではコンテンツをキャッシュするため、フィードファイルを更新する前にコンテンツが完全にアップロードされ、利用できる状態になっていることが重要です。新しいコンテンツを確実に利用できるように、以下の手順を実施します。

  1. サーバーにコンテンツをアップロードし、アップロードが完了するまで待機して、エンドポイントに到達できることを確認します。
  2. 現在の日付と時刻を反映するよう、フィードファイルの日付要素を更新します。詳細については、フィード形式の詳細を参照してください。
  3. フィードファイルを保存します。

Alexaは15分ごとに新しいコンテンツの有無をチェックします。新しいコンテンツを見たり聞いたりすることができるようになるのは、フィードファイルの更新から30分以内です。

フィード形式の詳細

以下の表に、サポートされる形式ごとの詳細情報をまとめました。メッセージにはそれぞれ、ペイロードの形式を指定するHTTP content-typeヘッダーが必要です。以下の表の残りの項目には、フィード内の各項目の形式情報が説明されています。

要素 JSON要素 RSS要素 説明 必須
HTTP Content-Typeヘッダー application/json application/rss+xml フィードペイロードの形式です。
ID uid guid フィード項目ごとに一意のIDです。UUID形式が推奨されますが、必須ではありません。
日付 updateDate pubDate UTC/Zulu時で指定されるyyyy-MM-dd'T'HH:mm:ss'.0Z'形式の日付です。Dateはフィード項目の新しさを表し、項目は新しいものから古いものの順に表示されます。Alexaでは7日以上前の日付の項目は無視されます。
タイトル titleText title Alexaアプリに表示されるフィード項目のタイトルです。
オーディオコンテンツ MP3ストリームのURLの値を持つstreamUrl要素です。 typeアトリビュートにaudio/mpegを設定したenclosure要素です。 Alexaがユーザーに再生するオーディオです。オーディオコンテンツの場所を表すHTTPS URLです。このフィールドはオーディオ項目には必須です。
テキストコンテンツ mainText description Alexaがユーザーに読み上げるテキストです。オーディオ項目の場合、この要素は無視されるため、空の文字列("")を指定できます。
表示URL redirectionUrl link Alexaアプリのもっと見るリンクのリンク先URLを指定します。

JSONメッセージの例

以下の例では、フラッシュブリーフィングスキルAPI用にJSONをフォーマットする方法を表しています。

オーディオ項目を1つ含むJSONメッセージの例

この例には、Alexaがユーザーに対して再生するオーディオコンテンツが含まれています。タイトルとリンクがAlexaアプリに表示されます。

Content-Type: application/json
...
{
  "uid": "urn:uuid:1335c695-cfb8-4ebb-abbd-80da344efa6b",
  "updateDate": "2016-05-23T22:34:51.0Z",
  "titleText": "Amazon開発者ブログ、今週のまとめ5月23日",
  "mainText": "",
  "streamUrl": "https://developer.amazon.com/public/community/blog/myaudiofile.mp3",
  "redirectionUrl": "https://developer.amazon.com/public/community/blog"
}

テキスト項目を1つ含むJSONメッセージの例

この例には、Alexaがユーザーに対して読み上げるテキストコンテンツが含まれています。タイトルとリンクがAlexaアプリに表示されます。

Content-Type: application/json
...
{
  "uid": "urn:uuid:1335c695-cfb8-4ebb-abbd-80da344efa6b",
  "updateDate": "2016-05-23T00:00:00.0Z",
  "titleText": "Amazon開発者ブログ、今週のまとめ5月23日",
  "mainText": "エコシムをぜひお試しください。開発者がアマゾンエコーの外観や操作感をシミュレートできる新しいオンラインコミュニティツールです。",
  "redirectionUrl": "https://developer.amazon.com/public/community/blog"
}

複数のテキスト項目を含むJSONメッセージの例

以下の例には、Alexaがユーザーに対して読み上げる複数のテキスト項目が含まれています。項目の間でイアコン音声が再生されます。タイトルとリンクがAlexaアプリに表示されます。

Content-Type: application/json
...
[
  {
    "uid": "EXAMPLE_CHANNEL_MULTI_ITEM_JSON_TTS_1",
    "updateDate": "2016-04-10T00:00:00.0Z",
    "titleText": "複数項目のJSON(TTS)",
    "mainText": "このチャンネルには複数のTTS JSON項目があります。これは最初の項目です。",
    "redirectionUrl": "https://www.amazon.com"
   },
  {
    "uid": "EXAMPLE_CHANNEL_MULTI_ITEM_JSON_TTS_2",
    "updateDate": "2016-04-10T00:00:00.0Z",
    "titleText": "複数項目のJSON(TTS)",
    "mainText": "このチャンネルには複数のTTS JSON項目があります。これは2番目の項目です。",
    "redirectionUrl": "https://www.amazon.com"
  }
]

RSSメッセージの例

以下の例では、フラッシュブリーフィングスキルAPI用にRSSをフォーマットする方法を表しています。

オーディオ項目を1つ含むRSSメッセージの例

この例には、Alexaがユーザーに対して再生するオーディオコンテンツが含まれています。タイトルとリンクがAlexaアプリに表示されます。

Content-Type: application/rss+xml
...

<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
  <channel>
    <ttl>30</ttl>
    <item>
      <guid>urn:uuid:1335c695-cfb8-4ebb-abbd-80da344efa6b</guid>
      <title>Amazon開発者ブログ、今週のまとめ5月23日</title>
      <description>
        エコシムをぜひお試しください。開発者がアマゾンエコーの外観や操作感をシミュレートできる
        新しいオンラインコミュニティツールです。
      </description>
      <link>https://developer.amazon.com/public/community/blog</link>
      <pubDate>2016-05-23T00:00:00.0Z</pubDate>
      <enclosure url="https://developer.amazon.com/public/community/blog/myaudiofile.mp3"
		length="12216320" type="audio/mpeg" />
     </item>
  </channel>
</rss>

テキスト項目を1つ含むRSSメッセージの例

この例には、Alexaがユーザーに対して読み上げるテキストコンテンツが含まれています。タイトルとリンクがAlexaアプリに表示されます。

Content-Type: application/rss+xml
    ...

<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
  <channel>
    <ttl>30</ttl>
    <item>
      <guid>urn:uuid:42667ad2-0ffd-4f04-973f-732564622d7e</guid>
      <title>Amazon開発者ブログ、今週のまとめ5月23日</title>
      <link>https://developer.amazon.com/public/community/blog</link>
      <pubDate>2016-05-23T00:00:00.0Z</pubDate>
      <description>
        エコシムをぜひお試しください。開発者がアマゾンエコーの外観や操作感をシミュレートできる新しいオンラインコミュニティツールです。スリーディージャバスクリプトアニメーションとアレクサ音声サービスを搭載するエコシムを使用して、アレクサの機能やスキルを実際に操作できます。エコシムはブラウザで動くため、誰でもどこでもアクセスしてアレクサスキルをテストできます。
        もうスキルのテストにアレクサデバイスは不要です。世界中の開発者がエコシムを使用してアレクサを体験できます。
      </description>
     </item>
  </channel>
</rss>

複数のテキスト項目を含むRSSメッセージの例

以下の例には、Alexaがユーザーに対して読み上げる複数のテキスト項目が含まれています。項目の間でイアコン音声が再生されます。タイトルとリンクがAlexaアプリに表示されます。

Content-Type: application/rss+xml
...
<?xml version="1.0" encoding="UTF-8" ?>
<rss version="2.0">
  <channel>
    <ttl>30</ttl>
    <item>
      <title>複数項目のRSS(TTS)</title>
      <link>https://www.amazon.com</link>
      <pubDate>2016-05-23T00:00:00.0Z</pubDate>
      <description>このチャンネルには複数のTTS RSS項目があります。これは項目1です。</description>
      <guid>urn:uuid:b385254e-dc31-4c4a-afc5-0de97e43923c</guid>
    </item>
    <item>
      <title>複数項目のJSON(TTS)</title>
      <link>https://www.amazon.com</link>
      <pubDate>2016-05-23T00:00:00.0Z</pubDate>
      <description>このチャンネルには複数のTTS RSS項目があります。これは項目2です。</description>
      <guid>urn:uuid:cf093eed-66f2-4dee-bdad-02ff0510194b</guid>
    </item>
  </channel>
</rss>