定型アクションのカスタムトリガーを作成する手順

定型アクションのカスタムトリガーを作成する手順

定型アクションのカスタムトリガーを作成するには、次の手順を実行します。既存のスキルを更新するか、新しいスキルを作成することで、定型アクションのカスタムトリガーを実装できます。

前提条件

手順を実行する前に、次の要件を満たしておく必要があります。

  • Alexaスキルを公開している。
  • 定型アクション機能のカスタムトリガーを使用する許可を得る。開発者プレビューに参加するには、Amazonにご連絡ください。
  • Amazon開発者アカウントを作成する。
  • 最新バージョンのAlexa Skills Kitコマンドラインインターフェース（ASK CLI）をインストールする。詳細については、ASK CLIを参照してください。
  • REST（Representational State Transfer）クライアントまたはcurlコマンドラインツールをインストールする。

定型アクションのカスタムトリガーを作成する手順

定型アクションのカスタムトリガーAPIワークフロー

定型アクションのカスタムトリガーを作成するには、次の手順を実行します。

  1. スキルを作成し、スキルマニフェストを更新する。
  2. スキルを公開し、トリガーを定義して、開発環境にデプロイする。
  3. 定型アクションのコールバックをリッスンするようにスキルを更新する（UNICASTのみ）。
  4. トリガーをテストする。
  5. 開発エンドポイントを本番エンドポイントに変更する。
  6. ユーザーがトリガーを使用して定型アクションを設定する。
  7. REST APIを使用してトリガーインスタンスを送信する。

手順1： スキルを作成し、スキルマニフェストを更新する

最初に新しいスキルを作成し、次にroutinesセクションを追加してskill.jsonマニフェストを変更します。routinesスキルタイプは新しいトリガーを登録します。また、Alexaとスキルが安全にやり取りできるようにします。

1.1 スキルを作成する

開発者コンソールまたはASK CLIを使用して、新しいスキルを作成できます。

開発者コンソールでスキルを作成するには

ASK CLIを使用してスキルを作成するには

  • コマンドプロンプトでask newコマンドを実行します。

詳細については、ASK CLIのnewコマンドを参照してください。

1.2 スキルマニフェストskill.jsonを更新する

この手順では、スキルマニフェストファイルを更新します。

skill.jsonを更新するには

1. 開発者コンソールでスキルを作成した場合は、Alexaスキルをローカルワークスペースに複製できます。Alexaスキルを開発者コンソールからローカルワークスペースに複製するには、コマンドプロンプトでask init --hosted-skill-id <hosted-skill-id>コマンドを実行します。

詳細については、initコマンドを参照してください。

2. routinesを使用して、スキルマニフェストのapisセクションを更新します。定型アクションスキルマニフェストのパラメーターの説明については、定型アクションスキルマニフェストを参照してください。

3. スキルマニフェストにpremissions配列が存在することを確認します。permissions配列は、スキルが使用できる名前付き権限の配列を指定するために使用します。

詳細については、permissionsを参照してください。

4. skill.jsonにpermissionsがない場合は、手順4と手順7で{clientID}と{clientSecret}が定型アクションのカスタムトリガーAPIをセッション外で呼び出せるようにpermissionsを追加する必要があります。

次の例は、apisセクションにroutinesが追加され、premissionsセクションも追加されたスキルマニフェストを示しています。

5. スキルマニフェストを更新するには、ask smapi update-skill-manifest -g development -s <hosted-skill-id> -manifest "file:skill.json"コマンドを実行します。

6. （オプション）必要に応じて、アカウントリンクのサポートを追加します。

アカウントリンクの詳細については、Alexaスキルにアカウントリンクを追加するを参照してください。

手順2： スキルを公開し、トリガーを定義して、開発環境にデプロイする

手順2では、スキルを公開し、トリガーファイルを定義して、パッケージを開発環境にデプロイしてから、トリガー定義を送信して登録します。

2.1 スキルの認定を受けて公開する

トリガーをAlexaアプリに表示するには、スキルを公開する必要があります。そのため、まずスキルの認定を申請する必要があります。認定を受けたら、手順2.3でトリガー定義ファイルを作成して送信し、開発中ステージに登録できます。

スキルの認定を受けて公開するには

2.2 トリガー定義ファイルを作成する

この手順では、JSON形式のトリガー定義ファイルを作成します。トリガー定義ファイル名は、トリガーを使用可能にする予定のロケールと一致している必要があります（en-US.jsonなど）。

トリガー定義には、トリガー名、表示タイトル、配信タイプ、表示カテゴリー、キーワードが含まれている必要があります。トリガー定義要件の詳細については、トリガー定義を参照してください。

トリガー定義ファイルを作成するには

1. JSON形式（en-US.json など）のトリガー定義ファイルを作成します。

2. トリガー定義ファイルを/skill-package/routines/triggers/<トリガー名>ディレクトリに保存します。

次の例は、MyShoppingTriggerというトリガー名のスキルパッケージディレクトリを示しています。

3. トリガー定義JSONファイルにコンテンツを追加します。

次のJSONコードは、UNICAST配信タイプのトリガー定義例を示しています。

2.3 スキルを開発環境にデプロイし、トリガー定義を送信して登録する

まず、スキルをデプロイして、更新したマニフェストを登録します。次に、トリガー定義をAmazonに登録し、開発中のスキルを有効にします。

スキルをデプロイし、更新したトリガー定義を送信してスキルを有効にするには

1. スキルをデプロイするの手順に従います。

2. トリガー定義をAlexaに登録するには、Amazonに連絡して、トリガー定義のJSONファイルをAmazonに送信してください。

3. 登録するトリガー定義を送信したら、SMAPIのスキルの有効化REST API操作を使用して、開発中ステージでスキルを有効にする必要があります。PUTリクエストパスで{stage}をdevelopmentに設定します。この手順を実行することで、テストとデバッグを行っている間は、ユーザーはこのバージョンのトリガーにアクセスできなくなります。

手順3： 定型アクションのコールバックをリッスンするようにスキルを更新する（UNICASTのみ）

この手順はUNICASTトリガーのみが対象です。

UNICASTトリガーは、特定のユーザーに固有のトリガー通知です。対して、MULTICASTトリガーは汎用的で、複数の受信者間で共有されます。

手順2の例のように、トリガータイプ定義でUNICAST配信タイプを使用する場合は、トリガーのに興味があるユーザーを把握しておく必要があります。そのためには、ユーザーがトリガーを使用して定型アクションを作成したらリクエストが処理されるように、Alexaスキルを更新する必要があります。定型アクショントリガーのサービスプロバイダーインターフェース（SPI）をスキルに実装して、定型アクションの作成コールバックと削除コールバックを処理できるようにします。

スキルを更新して定型アクションのコールバックに応答するには

1. スキルマニフェストskill.jsonで、apisセクションにregionsオブジェクトとendpointオブジェクトを含めます。

詳細については、定型アクションのapisオブジェクトを参照してください。

2. リクエストのHTTPヘッダーに、リクエストの形式で説明されているのと同じAlexaスキルのリクエスト形式を使用します。

3. Alexaから送信されたリクエストを手動で検証するの手順に従って、リクエストがAlexaからのものであることを確認します。

4. （オプション）アマゾンウェブサービス（AWS）Lambdaにスキルをデプロイする場合は、Lambda関数のトリガーを設定するの指示に従って、AWS LambdaからASK権限を取得します。

5. トリガー作成イベントを処理するには、リクエストタイプRoutines.Trigger.Createを処理するようにスキルを更新する必要があります。

次のJavaScriptコードの例は、リクエストタイプ Routines.Trigger.Createを処理する方法を示しています。

次のJavaスキルコードの例では、AWS Lambdaを使用してRoutines.Trigger.CreateリクエストとRoutines.Trigger.Deleteリクエストを処理する方法を示しています。

定型アクショントリガーSPIの詳細については、定型アクショントリガーのサービスプロバイダーインターフェースを参照してください。

手順4： 開発アカウントでトリガーをテストする

この手順では、開発アカウントでスキルからトリガーインスタンスを受け取る定型アクションを作成します。

4.1 スキルを有効にして定型アクションを作成する

定型アクションを作成する前に、まず開発中ステージでスキルを有効にする必要があります。

スキルを有効にして定型アクションを作成するには

  1. Alexaアプリのホームページで、その他 > スキル・ゲーム > スキル > 開発をタップし、スキルの名前を探して有効にするをタップします。

  2. 手順2で定義したカスタムトリガーを使用して、定型アクションを作成します。

関連付けられたトリガーは、定型アクションDEVタグとともに表示されます。定型アクションを作成すると、AlexaからスキルにUnicastトリガーのSPIコールが送信されます。

4.2 curlコマンドを使用してアクセストークンを取得する

アクセストークンはcurlコマンドを使用して取得できます。

curlコマンドを使用してアクセストークンを取得するには

1. 次のcurlコマンドをコピーします。

2. 開発者コンソールの権限タブで、スキルのclientIDとclientSecretを探します。

3. {clientID}と{clientSecret}をコピーします。

4. 手順1のcurlコマンド構文に、clientIDとclientSecretを手順3の{clientID}と{clientSecret}のプレースホルダーに貼り付けます。

5. 定型アクショントリガーAPIによる認証で、スコープがscope=alexa::routines:triggerinstances:writeに設定されていることを確認します。

6. コマンドプロンプトで、前の手順で作成したcurlコマンドを実行します。

7. 次の成功応答の例のようなaccess_tokenを受信していることを確認します。この例では、Atc|で始まるアクセストークンが、手順4.3と手順7で使用できるベアラートークンです。通常、トークンには有効期限があります。この例では、トークンは1時間（3600秒）後に期限切れになります。

4.3 テストトリガーインスタンスを送信する

テストトリガーインスタンスをディスパッチするには、POSTリクエストを実行します。

テストトリガーインスタンスを送信するには

1. カスタムスキルリクエストのsessionオブジェクトに関するページで説明されているuserIdと同じAmazon idを探します。

2. Amazon idをターゲットとして、RESTクライアントまたはcurlコマンドを使用してPOSTリクエストを実行して、定型アクションのトリガーインスタンスREST APIを呼び出します。

トリガーインスタンスの送信については、トリガーインスタンスをディスパッチするを参照してください。

次の例は、トリガーインスタンスUNICASTの本文を示しています。

3. 202 OKの成功応答が返されることを確認します。

4. Alexaアプリの定型アクションを作成する実行条件を設定セクションで、Order status changesというタイトルのトリガーが表示されていることを確認します。

手順5：エンドポイントを本番エンドポイントに変更する

トリガーをテストしてスキルの品質を確認できたら、エンドポイントを開発エンドポイントから本番エンドポイントに変更します。

エンドポイントを本番エンドポイントに変更するには

1. スキルマニフェストskill.jsonで、エンドポイントを本番エンドポイントに更新して、新しいエンドポイントの変更が公開されていることを確認します。

2. 最新のトリガー定義を送信するには、Amazonに連絡して、スキルを公開するよう依頼してください。

本番エンドポイントの詳細については、本番エンドポイントを参照してください。

手順6：ユーザーにトリガーを使ってもらう

スキルが認定されて登録されたトリガーでトリガーインスタンスを送信できるようになると、ユーザーはAlexaアプリでこの新しいトリガーを使用して定型アクションを設定できます。

Alexaアプリでは、標準搭載のトリガーが表示されているのと同じ実行条件を設定セクションに、新しいトリガーが表示されます。

詳細については、Create an Alexa Routine in the Alexa App（英語のみ）を参照してください。

手順7： REST APIを使用して実際のトリガーインスタンスを送信する

これで、定型アクションのカスタムトリガーを設定し、トリガーインスタンスを送信できるようになりました。

REST APIを使用してトリガーインスタンスを送信するには

詳細については、トリガーインスタンスをディスパッチするを参照してください。REST API呼び出しのアクセストークンを取得する方法については、手順4.2 curlコマンドを使用してアクセストークンを取得するを参照してください。

動的パラメーターによるパーソナライズされたオプションの表示

動的パラメーター機能を使用して、パーソナライズされたオプションを表示できます。動的パラメーターを使用すれば、トリガー定義ファイルにあらかじめ定義されていないトリガーやパラメーターをユーザーに表示できます。これらのパラメーターは、スキルがサポートするSPIを介して返されます。

使用例については、動的パラメーターの例を参照してください。

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

最終更新日: 2025 年 11 月 10 日