ついに登場！AlexaのリマインダーAPIをカスタムスキルへ組み込む

スキルを作っていると、使いたくて仕方のなかったあの機能。「リマインダーへのアクセス」がついにカスタムスキルからできるようになりました。さっそく触ってみましょう。

Remind Customers of Important Tasks or Events with the Reminders API

権限の設定

リマインダーAPIへのアクセスは、ユーザーに許可を得てからしか実行できません。そのためスキル側ではまず[アクセス権限]画面からリマインダーをオンにする必要があります。

ASK CLIのmanifestファイルでは、以下のような書き方となります。

{
  "manifest": {
    ...
    "manifestVersion": "1.0",
    "permissions": [
      {
        "name": "alexa::alerts:reminders:skill:readwrite"
      }
    ],

alexa::alerts:reminders:skill:readwriteがリマインダーAPIですね。

アプリの設定

そしてテスト用のアプリ側でリマインダーを許可する必要があります。

これで事前準備が整いました。

APIアクセストークンの取得

※この記事はベータ版での実装メモです。この先の実装はask-sdkが対応するまでの実装方法ですのでご注意ください。

スキルのテスト画面やask simulateなどで一度スキルを実行させましょう。リクエストの値にある.context.System.apiAccessTokenの値を利用します。

curlでリクエストを組み立てる

まずはcurlでテストしてみましょう。基本形は以下の通りです。

curl https://api.amazonalexa.com/{path} \
 -H "Authorization:Bearer <.context.System.apiAccessTokenの値>" \
 -H 'Accept: application/json'

reminderを登録する

先ほどのAPIにPOSTを実行することでリマインダーを登録できます。例えば以下のような形です。SCHEDULED_RELATIVEを設定し、offsetInSecondsに秒数を入れることでrequestTimeから指定秒数経過後にリマインダーを出すことができます。

{
   "requestTime" : "2018-11-01T19:04:00.672" 
   "trigger": {
        "type" : "SCHEDULED_RELATIVE",
        "offsetInSeconds" : "7200",
   },
   "alertInfo": {
        "spokenInfo": {
            "content": [{
                "locale": "ja-JP",
                "text": "犬の散歩"
            }]
        }
    },
    "pushNotification" : {                            
         "status" : "ENABLED"
    }
}

リマインダーの一覧を取得

同じパスでGETすることでリマインダーの一覧を取得できます。レスポンスは以下のような形です。

{
  totalCount: 4,
  alerts:[{
        "alertToken": "d877f6b7-fe34-40fe-9029-a67a3f75140f",
        "createdTime": "2018-11-01T15:44:59.336Z",
        "updatedTime": "2018-11-01T15:50:24.561Z",
        "trigger": {
          "type": "SCHEDULED_ABSOLUTE",
          "scheduledTime": "2018-11-30T07:30:00.000",
          "timeZoneId": "Asia/Tokyo",
          "offsetInSeconds": 0,
          "recurrence": null
        },
        "status": "COMPLETED",
        "alertInfo": {
          "spokenInfo": {
            "content": [
              {
                "locale": "",
                "text": "Test Reminder",
                "ssml": ""
              }
            ]
          }
        },
        "pushNotification": {
          "status": "ENABLED"
        },
        "version": "3"
      }
...

ASK UtilsでReminder APIを(比較的)簡単によび出す

現時点ではまだask-sdkがReminder APIをサポートしていない様子です。ということで、このAPIを使うためには自力でリクエストを組み立てる必要があります。

個人的に使うことがあったので、ask-utilsの方にラッパーを用意しました。

npm i -S ask-utils@latestで最新版へアップしてからお試しください。

コードサンプル

いずれも async / await を前提としています。handlerInputを放り込んでやれば、APIアクセストークンやエンドポイントの指定・リクエストの作成をよしなにしてくれます。

const { RemidnerClient } = require('ask-utils')
// PUT new reminder
const client = new RemidnerClient(handlerInput)
const payload = {...}
client.setPayload(payload)
await client.fetch('POST')

// Lists reminder
const client = new RemidnerClient(handlerInput)
const lists = await client.fetch()

// Delete a reminder
const client = new RemidnerClient(handlerInput)
await client.fetch('DELETE', `/v1/alerts/reminders/${id}`)

リマインダー登録時のbody (payload)については決め打ちのクラスしか作っていないので、各自頑張って作ってください。