AlexaサービスAPIの呼び出し



AlexaサービスAPIの呼び出し

Alexa Skills Kitには、スキルエクスペリエンスをパーソナライズできる複数のサービスAPIが用意されています。SDKには、スキルのロジックからAlexa APIを簡単に呼び出すことができるサービスクライアントが含まれています。

ServiceClientFactory

ServiceClientFactoryは、HandlerInputコンテナオブジェクトからハンドラーで使用できます。個別のサービスクライアントの作成とApiAccessTokenおよびApiEndpointの設定を行います。

利用可能なメソッド

getDeviceAddressServiceClient() : deviceAddress.DeviceAddressServiceClient;
getDirectiveServiceClient() : directive.DirectiveServiceClient;
getListManagementServiceClient() : listManagement.ListManagementServiceClient;
getMonetizationServiceClient() : monetization.MonetizationServiceClient;
getReminderManagementServiceClient(): reminderManagement.ReminderManagementServiceClient;
getUpsServiceClient() : ups.UpsServiceClient;

ApiClient

ApiClientは、Alexaサービスに対してAPIコールを行うときにServiceClientFactoryによって使用されます。SDKを使用して、次のインターフェースに準拠する任意のカスタマイズ済みApiClientを登録できます。

インターフェース

interface ApiClient {
  invoke(request: ApiClientRequest): Promise<ApiClientResponse>;
}

interface ApiClientMessage {
  headers: Array<{key: string; value: string;}>;
  body?: string;
}

interface ApiClientRequest extends ApiClientMessage {
  url: string;
  method: string;
}

interface ApiClientResponse extends ApiClientMessage {
  statusCode: number;
}

DefaultApiClient

ask-sdk-coreパッケージは、DefaultApiClientを提供します。これは、Node.jsのネイティブhttpsクライアントを使用したApiClientの実装です。

コンストラクターの詳細

new DefaultApiClient() => object

DefaultApiClientオブジェクトを構築します。このオブジェクトは、ServiceClientが個別のAlexaサービスにAPTクラスを作成するために使用します。

DeviceAddressServiceClient

DeviceAddressServiceClientは、デバイスアドレスAPIに対してユーザーのAlexaデバイスに関連付けられた所在地データを照会するために使用できます。この所在地データを使用して、スキルの主要機能を提供したり、ユーザーエクスペリエンスを向上させることができます。たとえば、スキルはこの所在地情報を使って、近くの店舗の所在地一覧を提供したり、おすすめのレストランを紹介したりすることができます。

型定義

class DeviceAddressServiceClient {
  getCountryAndPostalCode(deviceId: string): Promise<services.deviceAddress.ShortAddress>;
  getFullAddress(deviceId: string): Promise<services.deviceAddress.Address>;
};

interface ShortAddress {
  countryCode?: string;
  postalCode?: string;
}

interface Address {
  addressLine1?: string;
  addressLine2?: string;
  addressLine3?: string;
  countryCode?: string;
  stateOrRegion?: string;
  city?: string;
  districtOrCounty?: string;
  postalCode?: string;
}

サンプルコード

以下は、DeviceAddressServiceClientのインスタンスを作成し、ユーザーの住所を取得するリクエストハンドラーの例です。

クリップボードにコピーされました。

const GetAddressIntent = {
  canHandle(handlerInput) {
    const { request } = handlerInput.requestEnvelope;

    return request.type === 'IntentRequest' && request.intent.name === 'GetAddressIntent';
  },
  async handle(handlerInput) {
    const { requestEnvelope, serviceClientFactory, responseBuilder } = handlerInput;
    const consentToken = requestEnvelope.context.System.user.permissions
        && requestEnvelope.context.System.user.permissions.consentToken;
    if (!consentToken) {
      return responseBuilder
        .speak('アマゾンアレクサアプリで位置情報の権限を有効にしてください。')
        .withAskForPermissionsConsentCard(['read::alexa:device:all:address'])
        .getResponse();
    }

    try {
      const { deviceId } = requestEnvelope.context.System.device;
      const deviceAddressServiceClient = serviceClientFactory.getDeviceAddressServiceClient();
      const address = await deviceAddressServiceClient.getFullAddress(deviceId);

      console.log('住所を正常に取得しました。ユーザーに応答しています。');

      let response;
      if (address.addressLine1 === null && address.stateOrRegion === null) {
        response = responseBuilder
          .speak(`住所が設定されていないようです。コンパニオンアプリで住所を設定できます。`)
          .getResponse();
      } else {
        const ADDRESS_MESSAGE = `住所は次のとおりです。${address.addressLine1}, ${address.stateOrRegion}, ${address.postalCode}`;
        response = responseBuilder
          .speak(ADDRESS_MESSAGE)
          .getResponse();
      }
      return response;
    } catch (error) {
      if (error.name !== 'ServiceError') {
        const response = responseBuilder
          .speak('申し訳ありません。エラーが発生しました。')
          .getResponse();

        return response;
      }
      throw error;
    }
  },
};

クリップボードにコピーされました。

import {
  HandlerInput,
  RequestHandler,
} from 'ask-sdk-core';
import {
  Response,
  services,
} from 'ask-sdk-model';
import Address = services.deviceAddress.Address;

const GetAddressIntent : RequestHandler = {
  canHandle(handlerInput : HandlerInput) : boolean {
    const { request } = handlerInput.requestEnvelope;

    return request.type === 'IntentRequest' && request.intent.name === 'GetAddressIntent';
  },
  async handle(handlerInput : HandlerInput) : Promise<Response> {
    const { requestEnvelope, serviceClientFactory, responseBuilder } = handlerInput;

    const consentToken = requestEnvelope.context.System.user.permissions
                         && requestEnvelope.context.System.user.permissions.consentToken;
    if (!consentToken) {
      return responseBuilder
        .speak('アマゾンアレクサアプリで位置情報の権限を有効にしてください。')
        .withAskForPermissionsConsentCard(['read::alexa:device:all:address'])
        .getResponse();
    }
    try {
      const { deviceId } = requestEnvelope.context.System.device;
      const deviceAddressServiceClient = serviceClientFactory.getDeviceAddressServiceClient();
      const address : Address = await deviceAddressServiceClient.getFullAddress(deviceId);

      console.log('住所を正常に取得しました。ユーザーに応答しています。');

      let response;
      if (address.addressLine1 === null && address.stateOrRegion === null) {
        response = responseBuilder
          .speak(`住所が設定されていないようです。コンパニオンアプリで住所を設定できます。`)
          .getResponse();
      } else {
        const ADDRESS_MESSAGE = `住所は次のとおりです。${address.addressLine1}, ${address.stateOrRegion}, ${address.postalCode}`;
        response = responseBuilder
          .speak(ADDRESS_MESSAGE)
          .getResponse();
      }

      return response;
    } catch (error) {
      if (error.name !== 'ServiceError') {
        const response = responseBuilder
          .speak('申し訳ありません。エラーが発生しました。')
          .getResponse();

        return response;
      }
      throw error;
    }
  },
};

DirectiveServiceClient

DirectiveServiceClientは、プログレッシブ応答APIにディレクティブを送信するために使用できます。プログレッシブ応答を使用すると、スキルがユーザーのリクエストへの完全な応答を準備している間もユーザーの関心を引き続けることができます。

型定義

class DirectiveServiceClient {
  enqueue(sendDirectiveRequest: services.directive.SendDirectiveRequest): Promise<void>;
}

interface SendDirectiveRequest {
  header: services.directive.Header;
  directive: services.directive.Directive;
}

interface Header {
  requestId: string;
}

type Directive = services.directive.SpeakDirective;

interface SpeakDirective {
  type: 'VoicePlayer.Speak';
  speech?: string;
}

サンプルコード

以下は、DirectiveServiceClientのインスタンスを作成してプログレッシブ応答を送信する関数の例です。

クリップボードにコピーされました。

function callDirectiveService(handlerInput, date) {
  const requestEnvelope = handlerInput.requestEnvelope;
  const directiveServiceClient = handlerInput.serviceClientFactory.getDirectiveServiceClient();

  const requestId = requestEnvelope.request.requestId;
  const directive = {
    header: {
      requestId,
    },
    directive: {
      type: 'VoicePlayer.Speak',
      speech: `$${date}の情報を検索しています。しばらくお待ちください...`,
    },
  };

  return directiveServiceClient.enqueue(directive);
}

クリップボードにコピーされました。

import { HandlerInput } from 'ask-sdk-core';
import { services } from 'ask-sdk-model';
import SendDirectiveRequest = services.directive.SendDirectiveRequest;

function callDirectiveService(handlerInput : HandlerInput, date : string) : Promise<void> {
  const requestEnvelope = handlerInput.requestEnvelope;
  const directiveServiceClient = handlerInput.serviceClientFactory.getDirectiveServiceClient();

  const requestId = requestEnvelope.request.requestId;

  const directive : SendDirectiveRequest = {
      header: {
          requestId,
      },
      directive: {
          type: 'VoicePlayer.Speak',
          speech: `$${date}の情報を検索しています。しばらくお待ちください...`,
      },
  };

  return directiveServiceClient.enqueue(directive);
}

ListManagementServiceClient

ListManagementServiceClientを使用して、Alexaのデフォルトリストやユーザーが保持しているカスタムリストの読み取りや変更を行うためにリスト管理APIにアクセスできます。

型定義

class ListManagementServiceClient {
  getListsMetadata(): Promise<services.listManagement.AlexaListsMetadata>;
  getList(listId: string, status: string): Promise<services.listManagement.AlexaList>;
  getListItem(listId: string, itemId: string): Promise<services.listManagement.AlexaListItem>;
  createList(createListRequest: services.listManagement.CreateListRequest): Promise<services.listManagement.AlexaListMetadata>;
  createListItem(listId: string, createListItemRequest: services.listManagement.CreateListItemRequest): Promise<services.listManagement.AlexaListItem>;
  updateList(listId: string, updateListRequest: services.listManagement.UpdateListRequest): Promise<services.listManagement.AlexaListMetadata>;
  updateListItem(listId: string, itemId: string, updateListItemRequest: services.listManagement.UpdateListItemRequest): Promise<services.listManagement.AlexaListItem>;
  deleteList(listId: string): Promise<void>;
  deleteListItem(listId: string, itemId: string): Promise<void>;
}

MonetizationServiceClient

スキル内課金サービス

ASK SDK for Node.jsには、inSkillPurchase APIを呼び出すMonetizationServiceClientが用意されています。このAPIでは、現在のスキルに関連付けられているすべてのスキル内商品を取得し、各商品が課金可能かまたは現在のユーザーが既に課金済みかを確認できます。次のメソッドがあります。

getInSkillProducts(locale : string, purchasable? : string, entitled? : string, productType? : string, nextToken? : string, maxResults? : number) : Promise<services.monetization.InSkillProductsResponse>
getInSkillProduct(locale : string, productId : string) : Promise<services.monetization.InSkillProduct>
  • localeは、リクエストのhandlerInput.requestEnvelope.request.localeから取得できます。
  • purchasableには、すべてのスキル内商品を取得する場合はnull、応答を課金可能かどうかで絞り込む場合はPURCHASABLEまたはNOT_PURCHASABLEを指定できます。
  • productTypeには、すべてのタイプのスキル内商品を取得する場合はnull、商品タイプで絞り込む場合はENTITLEMENTCONSUMABLE、またはSUBSCRIPTIONを指定できます。
  • entitledには、すべてのスキル内商品を取得する場合はnull、応答を買い切り型商品のステータスで絞り込む場合はENTITLEDまたはNOT_ENTITLEDを指定できます。
  • nextTokenは複数ページのクエリーの場合は必須です。maxResultsではスキルでAPI呼び出しごとに取得されるレコードの数を制御できます。デフォルトのページサイズは100レコードです。
  • productIdには取得するスキル内商品を指定します。

getInSkillProducts

getInSkillProductsメソッドは、現在のスキルに関連付けられているすべてのスキル内商品を取得し、現在のスキルとユーザーについて各スキル内商品の課金可能性と買い切り型商品のステータスを示します。

const LaunchRequestHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'LaunchRequest';
  },
  handle(handlerInput) {
    console.log("In LaunchRequest");

    const locale = handlerInput.requestEnvelope.request.locale;
    const ms = handlerInput.serviceClientFactory.getMonetizationServiceClient();

    return ms.getInSkillProducts(locale).then(function(result) {
      // inSkillProductsの結果を処理するコードがここに入ります
       const totalProducts = result.inSkillProducts.length;
       const purchasableProducts = result.inSkillProducts.filter(record => record.purchasable == 'PURCHASABLE');
       const entitledProducts = result.inSkillProducts.filter(record => record.entitled == 'ENTITLED');

       return handlerInput.responseBuilder
        .speak('合計' + result.inSkillProducts.length + '個の商品が見つかりました。そのうち' + purchasableProducts.length + '個が課金可能で、' + entitledProducts.length + '個が買い切られています。');
        .getResponse();
    });
  },
}

API応答にはスキル内商品レコードの配列が含まれます。

{
  "inSkillProducts":[
    {
      "productId": "amzn1.adg.product....",
      "referenceName": "<開発者が定義した製品参照名>",
      "type": "SUBSCRIPTION",               // またはENTITLEMENT
      "name": "<開発者が定義したロケール固有の製品名>",
      "summary": "<開発者が提供したロケール固有の製品説明>",
      "entitled": "ENTITLED",              // またはNOT_ENTITLED
      "purchasable": "PURCHASABLE",        // またはNOT_PURCHASABLE
      "purchaseMode": "TEST"               // またはLIVE
      "activeEntitlementCount": 1
    }
  ],
  "isTruncated": true,
  "nextToken": "string"
 }

getInSkillProduct

getInSkillProduct APIは指定されたproductIdで識別される単一のスキル内商品の商品レコードを取得します。

const LaunchRequestHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'LaunchRequest';
  },
  handle(handlerInput) {
    console.log("In LaunchRequest");

    const locale = handlerInput.requestEnvelope.request.locale;
    const productId = 'amzn1.adg.product.<GUID>';
    const ms = handlerInput.serviceClientFactory.getMonetizationServiceClient();

    return ms.getInSkillProduct(locale, productId).then(function(result) {
       // inSkillProductの結果を処理するコードがここに入ります
    });
  },
}

API応答には単一のスキル内商品レコードが含まれます。

{
  "productId": "amzn1.adg.product....",
  "referenceName": "<開発者が定義した製品参照名>",
  "type": "SUBSCRIPTION",               // またはENTITLEMENT
  "name": "<開発者が定義したロケール固有の製品名>",
  "summary": "<開発者が提供したロケール固有の製品説明>",
  "entitled": "ENTITLED",              // またはNOT_ENTITLED
  "purchasable": "PURCHASABLE",        // またはNOT_PURCHASABLE
  "purchaseMode": "TEST"               // またはLIVE
  "activeEntitlementCount": 1
}

これらのAPIとスキル実装での使い方の詳細については、こちらを参照してください。 カスタムスキルへのスキル内課金の追加

スキル内課金のインターフェース

ASK SDK for Node.jsには、スキルでAlexaからスキル内課金とキャンセルのリクエストを開始するためのaddDirective()メソッドが用意されています。Amazonシステムはユーザーとの音声による対話を管理し、課金取引を処理して、ステータス応答をリクエスト元のスキルに返します。このインターフェースを使用して、以下の3つのアクションがサポートされます。

  • Upsell
  • Buy
  • Cancel

これらのアクションと推奨されるユースケースの詳細については、こちらを参照してください。 カスタムスキルへのスキル内課金の追加

Upsell

スキルは、ユーザーが明示的にコンテキストをリクエストしなかった場合にスキルのコンテキストを提供するためにUpsellアクションを開始する必要があります。たとえば、無料のコンテンツが提供されている間または後です。Upsellアクションを開始するには、製品IDとアップセルメッセージが必要です。アップセルメッセージを使って、開発者はAlexaで価格を提示する前にユーザーにスキル内商品を提示する方法を指定できます。

// スキルフローでは、ユーザーから明示的な依頼なしで
// スキル内製品を提供するために意思決定がなされた場合

return handlerInput.responseBuilder
  .addDirective({
    'type': 'Connections.SendRequest',
    'name': 'Upsell',
    'payload': {
      'InSkillProduct': {
          'productId': '<アップセルしたいISPの製品ID>'
      },
      'upsellMessage': '<スキル内製品のアップセル用紹介説明>'
    },
    'token': 'correlationToken'
  })
  .getResponse();

Buy

スキルは、ユーザーが特定のスキル内商品の課金をリクエストしたときにBuyアクションを開始します。Buyアクションを開始するには、製品IDが必要です。

// スキル内製品を購入するためにユーザーのインテントをキャプチャするカスタムインテント
// (下記のbuyProductIntent)を実装し、次にAlexaに対してBuyリクエストを開始します。
// 例:'アレクサ、<商品名>を買って'

const buyProductIntentHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'IntentRequest'
      && handlerInput.requestEnvelope.request.intent.name === 'buyProductIntent';
  },
  handle(handlerInput) {
    // inSkillProducts APIを呼び出してリクエストしたスキル内商品の製品IDを取得します。
    // 以下のスロット変数productNameはデモ用です。

    const locale = handlerInput.requestEnvelope.request.locale;
    const ms = handlerInput.serviceClientFactory.getMonetizationServiceClient();

    return ms.getInSkillProducts(locale).then(function(res) {
      const slots = handlerInput.requestEnvelope.request.intent.slots;
      const productReferenceName = slots['productName'].value;
      const product_record = res.inSkillProducts.filter(record => record.referenceName == productRef);
      if (product_record.length > 0)  {
        return handlerInput.responseBuilder
          .addDirective({
            'type': 'Connections.SendRequest',
            'name': 'Buy',
            'payload': {
              'InSkillProduct': {
                'productId': product_record[0].productId
              }
            },
           'token': 'correlationToken'
          })
          .getResponse();
      }
      else {
        return handlerInput.responseBuilder
          .speak('申し訳ありません。その商品は課金できません')
          .getResponse();
      }
    });
  }
};

Cancel

スキルは、サポートされているスキル内商品の既存の非消費型アイテムまたはサブスクリプションのキャンセルをユーザーがリクエストしたときに、Cancelアクションを開始します。Cancelアクションを開始するには、製品IDが必要です。

const cancelIntentHandler = {
  canHandle(handlerInput) {
    return handlerInput.requestEnvelope.request.type === 'IntentRequest'
      && handlerInput.requestEnvelope.request.intent.name === 'cancelProductIntent';
  },
  handle(handlerInput) {
    // inSkillProducts APIを呼び出してリクエストしたスキル内商品の製品IDを取得します。
    // 以下のスロット変数productNameはデモ用です。

    const locale = handlerInput.requestEnvelope.request.locale;
    const ms = handlerInput.serviceClientFactory.getMonetizationServiceClient();

    return ms.getInSkillProducts(locale).then(function(res) {
      const slots = handlerInput.requestEnvelope.request.intent.slots;
      const productReferenceName = slots['productName'].value;
      const product_record = res.inSkillProducts.filter(record => record.referenceName == productReferenceName);

      if (product_record.length > 0)  {
        return handlerInput.responseBuilder
          .addDirective({
            'type': 'Connections.SendRequest',
            'name': 'Cancel',
            'payload': {
              'InSkillProduct': {
                'productId': product_record[0].productId
              }
            },
            'token': 'correlationToken'
          })
          .getResponse();
      }
      else  {
        return handlerInput.responseBuilder
          .speak('申し訳ありません。わかりません。');
          .getResponse();
      }
    });
  }
};

UpsServiceClient

UpsServiceClientを使用して、AlexaユーザープロフィールAPIに対してユーザーの連絡先情報を照会したり、Alexaユーザー設定APIに対してユーザーのタイムゾーン設定、長さの単位、および温度の単位を照会できます。

型定義

class UpsServiceClient {
  getProfileEmail(): Promise<string>;
  getProfileGivenName(): Promise<string>;
  getProfileMobileNumber(): Promise<services.ups.PhoneNumber>;
  getProfileName(): Promise<string>;
  getSystemDistanceUnits(deviceId: string): Promise<services.ups.DistanceUnits>;
  getSystemTemperatureUnit(deviceId: string): Promise<services.ups.TemperatureUnit>;
  getSystemTimeZone(deviceId: string): Promise<string>;
}

ReminderManagementServiceClient

ReminderManagementServiceClientを使用して、スキルからリマインダーを作成、管理するためにAlexaリマインダーAPIを照会できます。

型定義

class ReminderManagementServiceClient extends BaseServiceClient {
  deleteReminder(alertToken: string): Promise<void>;
  getReminder(alertToken: string): Promise<services.reminderManagement.GetReminderResponse>;
  updateReminder(alertToken: string, reminderRequest: services.reminderManagement.ReminderRequest): Promise<services.reminderManagement.ReminderResponse>;
  getReminders(): Promise<services.reminderManagement.GetRemindersResponse>;
  createReminder(reminderRequest: services.reminderManagement.ReminderRequest): Promise<services.reminderManagement.ReminderResponse>;
}

サンプルコード

以下は、ReminderManagementServiceClientのインスタンスを作成し、新しいリマインダーを作成するリクエストハンドラーの例です。

const CreateReminderIntent = {
  canHandle(handlerInput) {
    const { request } = handlerInput.requestEnvelope;
    return request.type === 'IntentRequest' && request.intent.name === 'CreateReminderIntent';
  },
  async handle(handlerInput) {
    const { requestEnvelope, serviceClientFactory, responseBuilder } = handlerInput;
    const consentToken = requestEnvelope.context.System.user.permissions
      && requestEnvelope.context.System.user.permissions.consentToken;
    if (!consentToken) {
      return responseBuilder
        .speak('Amazon Alexaアプリでリマインダーの権限を有効にしてください。')
        .withAskForPermissionsConsentCard(['alexa::alerts:reminders:skill:readwrite'])
        .getResponse();
    }

    try {
      const speechText = "了解です。 リマインダーを設定します。";

      const ReminderManagementServiceClient = serviceClientFactory.getReminderManagementServiceClient();
      const reminderPayload = {
        "trigger": {
          "type": "SCHEDULED_RELATIVE",
          "offsetInSeconds": "30",
          "timeZoneId": "Asia/Tokyo"
        },
        "alertInfo": {
          "spokenInfo": {
            "content": [{
              "locale": "ja-JP",
              "text": "犬の散歩"
            }]
          }
        },
        "pushNotification": {
          "status": "ENABLED"
        }
      };

      await ReminderManagementServiceClient.createReminder(reminderPayload);
      return responseBuilder
        .speak(speechText)
        .getResponse();

    } catch (error) {
      console.error(error);
      return responseBuilder
        .speak('申し訳ありません。エラーが発生しました。')
        .getResponse();
    }
  }
};