AlexaサービスAPIの呼び出し



AlexaサービスAPIの呼び出し

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

ServiceClientFactory

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

利用可能なメソッド

getDeviceAddressServiceClient() : deviceAddress.DeviceAddressServiceClient;
getDirectiveServiceClient() : directive.DirectiveServiceClient;
getEndpointEnumerationServiceClient() : endpointEnumeration.EndpointEnumerationServiceClient;
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オブジェクトを構築します。ServiceClientDefaultApiClient を使用して個々のAlexaサービスへのAPI呼び出しを行います。

StandardSkillBuilder は、デフォルトでApiClientを登録します。または、スキル開発者はApiClientを CustomSkillBuilderに登録することもできます。

ApiClientをCustomSkillBuilderに登録する

withApiClient関数を使用してApiClientをCustomSkillBuilderに登録します。

const skillBuilder = Alexa.SkillBuilders.custom();
skillBuilder.withApiClient(new DefaultApiClient());

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('Amazon Alexaアプリで位置情報の権限を有効にしてください。')
        .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('Amazon Alexaアプリで位置情報の権限を有効にしてください。')
        .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);
}

EndpointEnumerationServiceClient

EndpointEnumerationServiceClientを使用すると、スキルが操作できるユーザーのエンドポイントを取得できます。

型定義

class EndpointEnumerationServiceClient extends BaseServiceClient {
  getEndpoints(): Promise<services.endpointEnumeration.EndpointEnumerationResponse>; 
}

interface EndpointEnumerationResponse {
  endpoints?: Array<services.endpointEnumeration.EndpointInfo>; 
}

サンプルコード

次の例は、接続されたエンドポイントを取得する関数を示しています。

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

skill = Alexa.SkillBuilders.custom()
    ....
    .withApiClient(new Alexa.DefaultApiClient())

....

function getConnectedEndpointsResponse(handlerInput)
{
  return handlerInput.serviceClientFactory.getEndpointEnumerationServiceClient().getEndpoints();
}

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

MonetizationServiceClientIn-Skill Purchase Service API を呼び出して、現在のスキルに関連付けられているスキル内商品に関する情報、または有料スキルに関する情報を取得します。応答は、商品またはスキルが現在のユーザーによって購入可能であるか、またはすでに購入されているかを示します。スキル内課金の詳細については、スキル内課金とはを参照してください。有料スキルの詳細については、有料スキルとはを参照してください。

スキル内課金サービス

スキル内商品サービスでは、次のメソッドが提供されています。

getInSkillProducts(acceptLanguage : string, purchasable? : string, entitled? : string, productType? : string, nextToken? : string, maxResults? : number) : Promise<services.monetization.InSkillProductsResponse>
getInSkillProduct(acceptLanguage : string, productId : string) : Promise<services.monetization.InSkillProduct>
getInSkillProductsTransactions(acceptLanguage: string, productId?: string, status?: string, fromLastModifiedTime?: string, toLastModifiedTime?: string, nextToken?: string, maxResults?: number): Promise<services.monetization.InSkillProductTransactionsResponse>;
getVoicePurchaseSetting(): Promise<boolean>; 
  • acceptLanguageは、リクエストのhandlerInput.requestEnvelope.request.localeから取得できます。
  • purchasableには、すべてのスキル内商品を取得する場合はnull、応答を課金可能かどうかで絞り込む場合はPURCHASABLEまたはNOT_PURCHASABLEを指定できます。
  • entitledには、すべてのスキル内商品を取得する場合はnull、応答を買い切り型商品のステータスで絞り込む場合はENTITLEDまたはNOT_ENTITLEDを指定できます。
  • productTypeには、すべてのタイプのスキル内商品を取得する場合はnull、商品タイプで絞り込む場合はENTITLEMENTCONSUMABLE、またはSUBSCRIPTIONを指定できます。
  • nextTokenは複数ページのクエリーの場合は必須です。
  • maxResultsではスキルでAPI呼び出しごとに取得されるレコードの数を制御できます。デフォルトのページサイズは50レコードです。
  • statusは、PENDING_APPROVAL_BY_PARENTAPPROVED_BY_PARENTDENIED_BY_PARENTEXPIRED_NO_ACTION_BY_PARENT、もしくはトランザクションステータスに対する応答をフィルタリングするためのERRORです。status値が nullの場合、すべてのトランザクションを取得します。
  • fromLastModifiedTimeおよびtoLastModifiedTimeをUTC ISO 8601形式で指定すると、最後に変更されたタイムスタンプに基づいてトランザクションをフィルタリングできます。例:yyyy-MM-ddTHH:mm:ss.SSSZ。値がnullの場合、すべてのトランザクションを取得します。

getInSkillProducts

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

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

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

    return ms.getInSkillProducts(acceptLanguage).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

getInSkillProductAPIは指定されたproductIdで識別される単一のスキル内商品または単一の有料スキルの商品レコードを取得します。有料スキルの場合は、productId にスキルIDを設定します。

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

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

    return ms.getInSkillProduct(acceptLanguage, 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
}

詳細については、スキルコードにISPのサポートを追加するおよび 有料スキルのインターフェースリファレンスを参照してください。

getInSkillProductsTransactions

getInSkillProductsTransactionsメソッドは、以前の購入リクエストが拒否された場合など、スキル内商品トランザクションに関する情報を提供します。トランザクションのステータスまたは日付を指定してトランザクションを照会できます。このAPIは、子供向けスキルのトランザクションの最近の結果のみを返します。

  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.getInSkillProductsTransactions(locale).then(function(response) {
         // response.results(トランザクションのリスト)を処理するコードがここに入ります
         const totalTransaction = response.results.length;
         const pendingTransactions = response.results.filter(record => record.status == 'PENDING_APPROVAL_BY_PARENT');
         const approvedTransactions = response.results.filter(record => record.status == 'APPROVED_BY_PARENT');
         const deniedTransactions = response.results.filter(record => record.status == 'DENIED_BY_PARENT');
         return handlerInput.responseBuilder
          .speak('Found total ' + totalTransaction + ' transaction of which ' + pendingTransactions.length + ' are pending, ' + approvedTransactions.length + ' are approved and ' + deniedTransactions.length + ' are denied');
          .getResponse();
      });
    },
  }

成功の応答にはlastModifiedTimeでソートされたトランザクションのリストが含まれます。最新のトランザクションはインデックス0にあります。デフォルトでは、リストのトランザクション数は50で切り捨てられます。

 
  {
      "results": [
          {
              "status": "PENDING_APPROVAL_BY_PARENT",
              "productId": "amzn1.adg.product.unique-id-4",
              "createdTime": "2018-11-23T12:23:10.52Z",
              "lastModifiedTime": "2018-11-23T12:23:10.52Z"
          },
          {
              "status": "PENDING_APPROVAL_BY_PARENT",
              "productId": "amzn1.adg.product.unique-id-3",
              "createdTime": "2018-11-23T11:21:10.52Z",
              "lastModifiedTime": "2018-11-23T11:21:10.52Z"
          },
          {
              "status": "EXPIRED_NO_ACTION_BY_PARENT",
              "productId": "amzn1.adg.product.unique-id-3",
              "createdTime": "2018-11-20T12:23:10.52Z",
              "lastModifiedTime": "2018-11-21T12:23:10.52Z"
          },
          {
              "status": "DENIED_BY_PARENT",
              "productId": "amzn1.adg.product.unique-id-2",
              "createdTime": "2018-11-15T11:03:07.52Z",
              "lastModifiedTime": "2018-11-15T11:03:08.52Z"
          },
          {
              "status": "APPROVED_BY_PARENT",
              "productId": "amzn1.adg.product.unique-id-1",
              "createdTime": "2018-11-14T22:21:00.52Z",
              "lastModifiedTime": "2018-11-14T22:22:00.52Z"
          }
      ],
      "metadata": {
          "resultSet": {
              "nextToken": "EXAMPLE123456789ABCDEFGHI"
          }
      }
  }

詳細については、Build Premium Experiences for Kid Skills in the USを参照してください。

getVoicePurchaseSetting

getVoicePurchaseSettingメソッドは、アカウント所有者がAlexaアプリで選択した購入コントロール設定を取得します。

  const LaunchRequestHandler = {
    canHandle(handlerInput) {
      return handlerInput.requestEnvelope.request.type === 'LaunchRequest';
    },
    handle(handlerInput) {
      console.log("In LaunchRequest");
 
      const ms = handlerInput.serviceClientFactory.getMonetizationServiceClient();
 
      return ms.getVoicePurchaseSetting().then(function(response) {
         // 応答を処理するコード(trueまたはfalse)がここに入ります
         return handlerInput.responseBuilder
          .speak('Customer\'s purchase preference value is ' + response);
          .getResponse();
      });
    },
  }

API応答には、ブール値が含まれています。アカウント所有者がAlexaアプリで音声購入を有効にしている場合、値はtrueです。

詳細については、Build Premium Experiences for Kid Skills in the USを参照してください。

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

addDirective() メソッドは、スキル内課金と有料スキルの購入フローとキャンセルフローを開始します。Alexaはユーザーとの音声による対話を管理し、課金取引を処理して、ステータス応答をリクエスト元のスキルに返します。このインターフェイスでは以下のタスクがサポートされています。

  • Upsell
  • Buy
  • Cancel

これらのタスクと推奨されるユースケースの詳細については、 スキルコードにISPのサポートを追加するおよび 有料スキルの実装手順を参照してください。

Upsell

スキルはUpsellタスクを呼び出して、ユーザーが明示的に要求しなかった場合(スキルの無料コンテンツ提供中やその後など)に、スキル内商品を紹介できます。Upsellタスクには、productIdとアップセルメッセージが必要です。アップセルメッセージを使って、開発者は購入フローを開始する前にAlexaがユーザーにスキル内商品を提示する方法を指定できます。

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

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

Buy

ユーザーから特定の商品または有料スキルの購入 を求められた場合、スキルは購入タスクを呼び出す必要があります。このタスクでは、スキル内課金のための productId が必要です。有料スキルの場合は、productId にスキル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 acceptLanguage = handlerInput.requestEnvelope.request.locale;
    const ms = handlerInput.serviceClientFactory.getMonetizationServiceClient();

    return ms.getInSkillProducts(acceptLanguage).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();
      }
    });
  }
};

キャンセル

スキル内商品または有料スキルの既存の買い切り方商品またはサブスクリプションをキャンセルするようユーザーから求められた場合、スキルはキャンセルタスクを呼び出す必要があります。このタスクでは、スキル内課金のための productId が必要です。有料スキルの場合は、productId にスキルIDを設定します。

以下の例は、スキル内課金の キャンセル リクエストを示しています。

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

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

    return ms.getInSkillProducts(acceptLanguage).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 = "Great! リマインダーを設定しました。";

      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();
    }
  }
};

TimerManagementServiceClient

TimerManagementServiceClientを使用してAlexaタイマーAPIを呼び出すことで、スキルからタイマーの作成や管理ができます。ASK SDK for Node.jsでタイマーAPIを使用する方法については、TimerManagementServiceClientAPIリファレンスを参照してください。