カスタムタスクをAlexa定型アクションに統合する

Note: Sign in to the developer console to build or publish your skill.

注： Alexa定型アクションでのカスタムタスクの使用はベータ版として提供されており、フィードバックに基づく改善や今後の機能強化によって変更される場合があります。フィードバックを提供するには、Stack Overflowにアクセスし、customtasksinroutinesタグを付けて投稿してください。

子ども向けスキルとHIPAAスキルでは、Skill Connectionsを使用することができないため、カスタムタスクをAlexa定型アクションに統合することはできません。

カスタムタスクをAlexa定型アクションに統合すると、スキルに対するユーザーエンゲージメントを高めることができます。

まず、新しいカスタムタスクを作成するか、Skill ConnectionsやQuick Link用に作成済みのカスタムタスクを使用します。次に、このページの指示に従って、タスクを定型アクションに対応させます。

このトピックでは、例として架空の「マイニュース」スキルを使用します。

Alexa定型アクションとは

Alexa定型アクションは、トリガーとアクションで構成されます。トリガーとは、時刻（毎日午前7時）などのイベントや、「アレクサ、朝のセッションを始めて」などのユーザーリクエストです。アクションは、トリガーが発生したときにAlexaに実行させるタスクです。たとえば、ニュースのブリーフィングを行ってから天気予報を読み上げるようなことができます。ユーザーは、ビルトインのAlexa定型アクションを有効にすることも、Alexaアプリの定型アクションセクションでトリガーと定型アクションを選択して独自のカスタム定型アクションを作成することもできます。

次のセクションでは、アクションに組み込むためのカスタムタスクを公開する方法を説明します。ユーザーは、スキルのカスタムタスクを定型アクションに追加できます。

Alexaアプリでのカスタムタスクの表示画面

カスタムタスクを定義し、公開してAlexa定型アクションに統合すると、タスクはアクションとして表示されます。ユーザーは、Alexaアプリに表示されるアクションを選んで定型アクションを作成できます。

たとえば、「マイニュース」スキルの場合、ユーザーは次の手順を実行して、「マイニュース」スキルのカスタムタスクを呼び出す定型アクションを追加します。

Alexaアプリまたは音声で「マイニュース」スキルを有効にします。
Alexaアプリで、その他 > 定型アクションに移動します。
+をタップします。
定型アクション名を入力します。
実行条件を設定をタップし、定型アクションを開始する条件を選択します。
アクションを追加 > スキル > マイスキル > マイニュースをタップします。
マイニュースには、次のスクリーンショットに示すように、デフォルトの起動タスク（マイニュースを開く）と3つのカスタムタスクが表示されます。
デフォルトのタスクまたはカスタムタスクのいずれか1つを選択します。
次のスクリーンショットは、ユーザーがデフォルトのタスクを選択したときの確認画面を示しています。
注：このデフォルトのタスクでは、Alexaアプリはテンプレート文で「Alexaは{スキル名}を開きます」と表示します。この説明では、「マイニュース」はスキルマニフェストから抽出されるスキルの名前です。
定型アクションを保存します。

カスタムタスクの要件と制限

Alexa定型アクションに統合するためにカスタムタスクが満たす必要がある要件は次のとおりです。

タスクは認定済みかつ公開中で、指定した各マーケットプレイスで有効である必要があります。詳細については、多言語に対応するスキルを開発するおよびスキルストアの詳細と公開範囲を定義するを参照してください。
タスク定義ファイルで、x-amzn-alexa-access-scopeフィールドは、vendor-privateではなく、publicに設定する必要があります。

注：カスタムタスクに表示される情報に不適切な内容が含まれている場合、スキルは認定されません。

現在、以下の制限事項が適用されています。

Alexa定型アクションに統合するには、カスタムタスクに複数の入力パラメーターを使用できません。
タスクのバージョン管理はサポートされていません。

カスタムタスクをAlexa定型アクションに統合する手順

カスタムタスクをAlexa定型アクションに統合するには、以下の手順を実行します。

カスタムタスクを作成します。
ロケールを選択します。
タスク定義ファイルを更新します。
スキルを検証します。
スキルの認定を受けて公開します。

ステップ1：カスタムタスクを作成する

スキルにカスタムタスクを追加するの手順に従って、スキルにカスタムタスクを構築します（作成していない場合）。

ステップ2：ロケールを選択する

どこのロケールでカスタムタスクをAlexa定型アクションとして利用できるようにするかを決めます。有効なロケールは、en-AU、en-CA、en-IN、en-GB、en-US、fr-CA、fr-FR、de-DE、hi-IN、it-IT、ja-JP、pt-BR、es-ES、es-MX、es-USです。

次の手順で説明するように、選択したロケールごとに、タスク定義ファイルでユーザーにわかりやすいタスクタイトルとタスクの説明を指定する必要があります。

注：タスク定義ファイルに特定ロケールのタスクタイトルとタスクの説明が指定されていない場合、そのロケールのAlexa定型アクションにタスクは表示されません。

ステップ3：タスク定義ファイルを更新する

タスク定義ファイルでは、タスクタイトル、タスクの説明、入力パラメーター名、入力パラメーターの説明に、適切な言語でユーザーにわかりやすい文字列を指定する必要があります。これらの文字列は、Alexaアプリでユーザーに表示されます。

カスタムタスクが入力パラメーターを使用する場合は、入力パラメーターのタイトルと説明も指定する必要があります。

詳細については、カスタムタスクのタイプ別タスク定義ファイルを参照してください。

ステップ4：スキルを検証する

Alexa Skills Kit開発者コンソールを使用して、以下の方法でスキルを検証できます。

スキルを検証する方法

開発者コンソールにログインし、スキルに移動します。
画面上部の認定タブを選択します。
実行をクリックします。
検証が完了したら、警告またはエラーメッセージがないか確認します。
ユーザーが定型アクションを設定するときにカスタムタスクが表示されるようにするには、警告とエラーメッセージに対処する必要があります。

スキルの検証の詳細については、スキルをテストして認定を申請するを参照してください。

ヒント： developmentステージのスキルで、カスタムタスクと定型アクションの統合をテストできます。詳細については、Alexa定型アクションを使用したカスタムタスクのテストを参照してください。

ステップ5：スキルの認定を受けて公開する

ユーザーが定型アクションを設定するときにカスタムタスクが表示されるようにするには、スキルを認定および公開する必要があります。詳細については、スキルを申請するおよび認定されたスキルを公開するを参照してください。

スキルの認定を申請するには、以下の点に留意してください。

スキル認定の一環として、Amazonはタスクスキーマを検証し、定型アクションとの互換性を確認します。
このページに記載されているカスタムタスクのスキーマは、定型アクションとの統合をサポートする唯一のスキーマです。
タスク定義ファイルに特定ロケールのタスクタイトルとタスクの説明が指定されていない場合、そのロケールのAlexa定型アクションにタスクは表示されません。
カスタムタスクと定型アクションに互換性がない場合でも、検証ステップでエラーメッセージが返されない限り、Skill ConnectionsとQuick Linkにカスタムタスクを使用できます。

スキルが認定を受けてliveステージに公開されると、カスタムタスクはAlexa定型アクションとして利用できるようになります。

カスタムタスクのタイプ別タスク定義ファイル

Alexa定型アクションは現在のところ次の3種類のカスタムタスクをサポートしています。

入力パラメーターなしのカスタムタスク
1つの文字列入力パラメーターを取るカスタムタスク
スキルがサポートする定義済みの入力セットを持つカスタムタスク

以下のセクションでは、サポートされているカスタムタスクタイプを定型アクションに統合するためにタスク定義ファイルに含める必要があるフィールドについて説明します。

入力パラメーターなしのカスタムタスク

次の表は、入力パラメーターなしのタスクをAlexa定型アクションに統合するときに含める必要があるタスク定義ファイルのフィールドを示しています。

フィールド	説明	型	必須
`info.x-amzn-display-details.{locale}.title`	カスタムタスクの名前。Alexaアプリでは、この名前は指定されたロケールのユーザーに表示されます。最大長： 50文字。	文字列	◯
`info.x-amzn-display-details.{locale}.description`	カスタムタスクで実行できることについての説明。Alexaアプリでは、この説明は指定されたロケールのユーザーに表示されます。最大長： 250文字。	文字列	◯
`info.x-amzn-alexa-access-scope`	このフィールドは`public`に設定する必要があります。	文字列	◯

注：タスクが完了したときに定型アクションが受け取るステータスを定義するには、responsesオブジェクトを使用します。詳細については、タスク定義ファイルのresponsesオブジェクトを参照してください。

例

以下の例は、「最新ニュース」カスタムタスクのタスク定義です。このタスクでは、ユーザーからの入力パラメーターは必要ありません。定型アクションのタスクを有効にするために、x-amzn-display-detailsフィールドにはユーザーにわかりやすいタスクタイトルと説明の文字列が入っています。

{
    "openapi":"3.0.0",
    "info":{
       "title":"最新ニュース",
       "version":"1",
       "x-amzn-alexa-access-scope":"public",
       "x-amzn-display-details":{
          "ja-JP":{
             "title":"最新ニュース",
             "description":"最新ニュースを読み上げます"
          },
          "es-US":{
             "title":"Actualización de las noticias",
             "description":"Reproducir actualización de noticias"
          }
       }
    },
    "paths":{
       "/NewsUpdate":{
          "post":{
             "requestBody":{
                "content":{
                   "application/json":{
                      "examples":{
                         "sampleInput":{
                            "description":"空の入力",
                            "value":{

                            }
                         }
                      }
                   }
                }
             },
             "responses":{
                "200":{
                   "description":"テストが正常に完了した場合",
                   "content":{
                      "application/json":{
                         "schema":{
                            "$ref":"#/components/schemas/SuccessfulResponse"
                         }
                      }
                   }
                },
                "400":{
                   "description":"指定されたパラメーターが検証に失敗した場合"
                },
                "500":{
                   "description":"タスクの実行に失敗した場合"
                }
             }
          }
       }
    },
    "components":{
       "schemas":{
          "SuccessfulResponse":{
             "type":"object",
             "properties":{
                "endTime":{
                   "type":"string",
                   "format":"date-time"
                }
             }
          }
       }
    }
 }

Alexaアプリの定型アクションリストに、infoオブジェクトに入力したわかりやすい文字列が表示されます。この場合、入力パラメーターはありません。ユーザーがアクション一覧から「最新ニュース」を選択すると、Alexaアプリから確認画面にリダイレクトされます。

次のスクリーンショットは、入力パラメーターなしの「最新ニュース」タスクの確認画面の例です。

1つの文字列入力パラメーターを取るカスタムタスク

1つの文字列入力パラメーターを取るカスタムタスクを作成できます。これらのタスクでは、以下の推奨事項を検討してください。

入力の最小および最大の長さ：オプションのminLengthフィールドとmaxLengthフィールドを使用して、エンドユーザーが入力パラメーター値として入力できる最小、最大の長さを指定できます。minLengthは正の整数で指定する必要があります。maxLengthはminLength以上の値を指定する必要があります。デフォルトのmaxLength値は100です。
想定外のテキスト入力：ユーザーはAlexaアプリで任意の文字列を入力パラメーターとして入力できるため、想定外のテキストが入力された場合にもタスクで適切に処理する必要があります。たとえば、タスクがサポートしていないテキスト入力をユーザーが入力した場合、入力した値がサポートされていないことをユーザーに知らせる応答を指定します。

次の表は、1つの文字列パラメーターを取るタスクをAlexa定型アクションに統合するときに含める必要があるタスク定義ファイルのフィールドを示しています。

フィールド	説明	型	必須
`info.x-amzn-display-details.{locale}.title`	カスタムタスクの名前。Alexaアプリでは、この名前は指定されたロケールのユーザーに表示されます。最大長： 50文字。	文字列	◯
`info.x-amzn-display-details.{locale}.description`	カスタムタスクで実行できることについての説明。Alexaアプリでは、この説明は指定されたロケールのユーザーに表示されます。最大長： 250文字。	文字列	◯
`components.schemas.Input.properties.company.x-amzn-display-details.{locale}.name`	入力パラメーターのタイトル。最大長： 50文字。	文字列	◯
`components.schemas.Input.properties.company.x-amzn-display-details.{locale}.description`	入力パラメーターで実行できることについての説明。最大長： 250文字。	文字列	◯
`info.x-amzn-alexa-access-scope`	このフィールドは`public`に設定する必要があります。	文字列	◯

例

以下は、「株価」カスタムタスクの例です。「最新ニュース」のカスタムタスク同様、このタスクにはユーザーにわかりやすい文字列を含むx-amzn-display-detailsフィールドがあります。

また、このタスクには銘柄コードという1つの文字列入力パラメーターが必要です。pathsオブジェクトの別のx-amzn-display-detailsフィールドに、パラメーター名と説明のわかりやすい文字列を指定します。

{
    "openapi":"3.0.0",
    "info":{
       "title":"株価",
       "version":"1",
       "x-amzn-alexa-access-scope":"public",
       "x-amzn-display-details":{
          "ja-JP":{
             "title":"株価",
             "description":"選択した株式の株価の情報を提供します"
          },
          "es-US":{
             "title":"Actualización de stock",
             "description":"Alexa le proporcionará la actualización de stock para el stock elegido."
          }
       }
    },
    "paths":{
       "/StockUpdate":{
          "post":{
             "requestBody":{
                "content":{
                   "application/json":{
                      "schema":{
                         "$ref":"#/components/schemas/Input"
                      },
                      "examples":{
                         "testExample":{
                            "summary":"株価タスクの入力例",
                            "description":"株価タスクの入力例",
                            "value":{
                               "company":"AMZN"
                            }
                         }
                      }
                   }
                }
             },
             "responses":{
                "200":{
                   "description":"テストが正常に完了した場合",
                   "content":{
                      "application/json":{
                         "schema":{
                            "$ref":"#/components/schemas/SuccessfulResponse"
                         }
                      }
                   }
                },
                "400":{
                   "description":"指定されたパラメーターが検証に失敗した場合"
                },
                "500":{
                   "description":"タスクの実行に失敗した場合"
                }
             }
          }
       }
    },
    "components":{
       "schemas":{
          "Input":{
             "type":"object",
             "properties":{
                "company":{
                   "type":"string",
                   "x-amzn-display-details":{
                      "ja-JP":{
                         "name":"銘柄コード",
                         "description":"銘柄コードを入力してください"
                      },
                      "es-US":{
                         "name":"Símbolo stock",
                         "description":"Ingrese el símbolo de stock"
                      }
                   }
                }
             }
          },
          "SuccessfulResponse":{
             "type":"object",
             "properties":{
                "endTime":{
                   "type":"string",
                   "format":"date-time"
                }
             }
          }
       }
    }
 }

この場合、アクションには文字列入力パラメーターが含まれます。ユーザーがアクション一覧から株価を選択すると、Alexaアプリからテキスト入力フィールドのある画面にリダイレクトされます。Alexaアプリでは、入力フィールドのヒントテキストとしてpathsオブジェクトのinfo.x-amzn-display-details.{locale}.descriptionに指定したわかりやすい文字列が表示されます。

次のスクリーンショットは、1つのパラメーターを取る「株価」タスクの入力画面です。選択した銘柄を文字列入力として入力することをユーザーに促す「銘柄コードを入力してください」というプロンプトが表示されます。

株価タスクの入力画面。ユーザー入力前には「銘柄コードを入力してください」のプロンプトが表示されます。

ユーザーがプロンプトをタップして銘柄コードを入力すると、プロンプトは消え、銘柄コードが表示されます。

株価タスクの入力画面。ユーザーが銘柄コード「AMZN」を入力するとプロンプトは消えます。

スキルがサポートする定義済みの入力セットを持つカスタムタスク

定義済みの入力セットを持つカスタムタスクを作成できます。1つのカスタムタスクは最大100個の定義済みの入力を持つことができます。

次の表は、定義済みの入力セットを持つタスクを定型アクションに統合するときに含める必要があるタスク定義ファイルのフィールドを示しています。

フィールド	説明	型	必須
`info.x-amzn-display-details.{locale}.title`	カスタムタスクの名前。Alexaアプリでは、この名前は指定されたロケールのユーザーに表示されます。最大長： 50文字。	文字列	◯
`info.x-amzn-display-details.{locale}.description`	カスタムタスクで実行できることについての説明。Alexaアプリでは、この説明は指定されたロケールのユーザーに表示されます。最大長： 250文字。	文字列	◯
`components.schemas.Input.properties.enumName.x-amzn-display-details.{locale}.name`	入力パラメーターのタイトル。最大長： 50文字。	文字列	◯
`components.schemas.Input.properties.enumName.x-amzn-display-details.{locale}.enums`	タスク入力に対して定義されている`enum`のリゾルバーの一覧。最大長： 250文字。	オブジェクト	◯
`components.schemas.Input.properties.enumName.x-amzn-display-details.{locale}.enums['{ENUM}']`	開発者が定義する入力。定義済みの入力パラメーターの最大長： 50文字。	文字列	◯
`info.x-amzn-alexa-access-scope`	このフィールドは`public`に設定する必要があります。	文字列	◯

例

以下の例では、ユーザーが選択できるニュースカテゴリーの一覧を表示します。ユーザーは、表示されたニュースカテゴリーのいずれかを選択できます。タスクにより、選択したカテゴリーの最新ニュースが配信されます。

{
    "openapi": "3.0.0",
    "info": {
      "title": "ニュースカテゴリー",
      "version": "1",
      "x-amzn-alexa-access-scope": "public",
      "x-amzn-display-details": {
        "ja-JP": {
          "title": "ニュースカテゴリー ",
          "description": "選択されたニュースカテゴリーの最新ニュースを読み上げます。"
        },
        "es-US": {
          "title": "Categorí de noticias",
          "description": "Reproducir actualización de noticias de la categoría de noticias seleccionada."
        }
      }
    },
    "tags": [{"name": "News category"}],
    "paths": {
      "/NewsCategory": {
        "summary": "ニュースカテゴリー",
        "description": "選択されたニュースカテゴリーの最新ニュースを読み上げます。",
        "post": {
          "requestBody": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Input"
                },
                "examples": {
                    "testExample": {
                        "summary": "最新ニュース読み上げタスクの入力例",
                        "description": "最新ニュース読み上げタスクの入力例",
                        "value": {
                            "ニュースカテゴリー": "POLITICS"
                        }
                    }
                }
              }
            }
          },
          "responses": {
            "200": {
              "description": "タスクが正常に完了した場合",  
              "content": {
                "application/json": {
                  "schema": {
                    "$ref": "#/components/schemas/SuccessfulResponse"
                  }
                }
              }
            },
            "400": {
              "description": "指定されたパラメーターが検証に失敗した場合"
            },
            "500": {
              "description": "タスクの実行に失敗した場合"
            }
          }
        }
      }
    },
    "components": {
      "schemas": {
        "Input": {
          "type": "object",
          "properties": {
            "enumName": {
              "type": "string",
              "enum": [
                "POLITICS","SPORTS","BUSINESS","TECHNOLOGY"
              ],
              "x-amzn-display-details": {
                "ja-JP": {
                  "name": "ニュースカテゴリー",
                  "enums": {
                    "POLITICS":"政治",
                    "SPORTS":"スポーツ",
                    "BUSINESS":"ビジネス",
                    "TECHNOLOGY":"テクノロジー"
                  }
                },
                "es-US": {
                  "name": "Categoría de noticias",
                  "enums": {
                    "POLITICS":"Política",
                    "SPORTS":"Deportes",
                    "BUSINESS":"Negocio",
                    "TECHNOLOGY":"Tecnología"
                  }
                }
              }
            }
          }
        },
        "SuccessfulResponse": {
          "type": "object",
          "properties": {
            "endTime": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      }
    }
  }

次のスクリーンショットは、4種類のニュースカテゴリーを提供する"ニュースカテゴリー"というカスタムタスクを示しています。ユーザーは、定型アクションに追加するカテゴリーを選択できます。

タスク定義ファイルのresponsesオブジェクト

タスク定義ファイルのresponsesオブジェクトは、タスク完了時にタスクのリクエスター（この場合は定型アクション）が受け取るステータスを定義します。

これらのステータスはHTTPステータスコードに似ています。次の表は、デフォルトで指定されているresponsesステータスを示しています。

responsesのステータス	説明
400	リクエストが、指定されたタスク定義に対するスキーマの検証に失敗したことを示します。たとえば、下限が上限よりも大きい場合などです。
403	リクエストされたタスクがアクセスを拒否されたことを示します。
404	リクエストされたタスクが存在しないか、タスクのプロバイダーが存在しないことを示します。

タスク定義ファイルのresponsesオブジェクトで独自のステータスを定義できます。たとえば、カウントダウンタスクの場合、次の例に示すように200、400、500のステータスを定義することができます。

{
   "openapi": "3.0.0",
   "info": {
     "title": "数字カウントダウンタスク",
     "version": "1",
     "x-amzn-alexa-access-scope": "public"
   },
   "tags": [{
     "name": "カウントダウン"
   }],
   "paths": {
     "/CountDown": {
       "summary": "カウントダウン",
       "description": "カウントダウンを開始します",
       "post": {
         "requestBody": {
           "content": {
             "application/json": {
               "schema": {
                 "$ref": "#/components/schemas/Input"
               }
             }
           }
         },
         "responses": {
           "200": {
             "description": "カウントダウンタスクが正常に終了しました。",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/SuccessfulResponse"
                 }
               }
             }
           },
           "400": {
             "description": "指定されたパラメーターが検証に失敗しました。たとえば、lowerLimitがupperLimitよりも大きい場合などです。"
           },
           "500": {
             "description": "内部エラーのため、カウントダウンタスクが失敗しました。"
           }
         }
       }
     }
   },
   "components": {
     "schemas": {
       "Input": {
         "type": "object",
         "properties": {
           "upperLimit": {
             "type": "number",
             "maximum": 100,
             "minimum": 1
           },
           "lowerLimit": {
             "type": "number",
             "maximum": 100,
             "minimum": 1
           }
         }
       },
       "SuccessfulResponse": {
         "type": "object",
         "properties": {
           "endTime": {
             "type": "string",
             "format": "date-time"
           }
         }
       }
     }
   }
}

カスタムタスクパラメーターのベストプラクティス

開発者やユーザーのプライバシーとセキュリティを保護する必要があります。定型アクションのカスタムタスクを設計する場合は、次の推奨事項を考慮してください。

カスタムタスクのパラメーターに、ユーザー個人を特定できる情報（PII）を示す可能性のある名前または値を含めないでください。PIIデータには、ユーザーの名前、住所、メールアドレス、クレジットカード番号などの情報が含まれます。
カスタムタスクの説明はタスクの動作を明確に示し、入力パラメーターの説明は想定されるユーザーからの入力を示す必要があります。このようにすることで、ユーザーは情報を得たうえで選択を行うことができます。

重要： カスタムタスクを定型アクションに統合後もタスクを引き続きサポートし、下位互換性のない変更を導入しないことを強くお勧めします。導入すると、既存の定型アクションがエラーになり、ユーザーエクスペリエンスが低下する可能性があります。

このページは役に立ちましたか？

フィードバックを送信

最終更新日: 2023 年 05 月 15 日

カスタムタスクをAlexa定型アクションに統合する

Alexa定型アクションとは

Alexaアプリでのカスタムタスクの表示画面

カスタムタスクの要件と制限

カスタムタスクをAlexa定型アクションに統合する手順

ステップ1： カスタムタスクを作成する

ステップ2： ロケールを選択する

ステップ3： タスク定義ファイルを更新する

ステップ4： スキルを検証する

ステップ5： スキルの認定を受けて公開する

カスタムタスクのタイプ別タスク定義ファイル

入力パラメーターなしのカスタムタスク

例

1つの文字列入力パラメーターを取るカスタムタスク

例

スキルがサポートする定義済みの入力セットを持つカスタムタスク

例

タスク定義ファイルのresponsesオブジェクト

カスタムタスクパラメーターのベストプラクティス

関連トピック

このページは役に立ちましたか？

ステップ1：カスタムタスクを作成する

ステップ2：ロケールを選択する

ステップ3：タスク定義ファイルを更新する

ステップ4：スキルを検証する

ステップ5：スキルの認定を受けて公開する