アトリビュートの管理



アトリビュートの管理

SDKを使うと、さまざまなスコープでアトリビュートの保存と取得が可能になります。たとえば、アトリビュートを使って後続のリクエストで取得するデータを保存できます。また、ハンドラーのcanHandleロジックでアトリビュートを使うことで、リクエストのルーティングに影響を与えることも可能です。

アトリビュートは、キーと値で構成されます。キーはString型で強制型、値は無制限のObject型です。セッションアトリビュートと永続アトリビュートの場合、値は保存して後で取得できるよう、シリアライズできるデータ型である必要があります。この制限はリクエストレベルのアトリビュートには適用されません。なぜならリクエストレベルのアトリビュートは、リクエスト処理のライフサイクルが終了すると、永続的に存在しないからです。

アトリビュートのスコープ

リクエストアトリビュート

リクエストアトリビュートは、1回のリクエスト処理ライフサイクルの間のみ存続します。リクエストを受信した時点では、リクエストアトリビュートは空です。また応答が生成されると破棄されます。

リクエストアトリビュートは、リクエストと応答のインターセプターと合わせて使うと便利です。たとえば、リクエストインターセプターを使って追加のデータとヘルパークラスをリクエストアトリビュートに挿入して、リクエストハンドラーから取得できるようにすることが可能です。

セッションアトリビュート

セッションアトリビュートは、現在のスキルセッションが継続している間存続します。セッションアトリビュートは、すべてのセッション内リクエストで使用できます。リクエスト処理のライフサイクル中に設定されたすべてのアトリビュートはAlexaサービスに返され、同じセッションの次のリクエストで提供されます。

セッションアトリビュートで、外部ストレージソリューションを使用する必要はありません。セッションアトリビュートはセッション外のリクエストの処理では使用できません。スキルセッションがクローズされると破棄されます。

永続アトリビュート

永続アトリビュートは、現在のセッションのライフサイクルが終了しても存続します。主要なスコープ(ユーザーID、デバイスID)、TTL、ストレージレイヤーを含む、これらのアトリビュートがどのように保存されるかは、PersistenceAdapterのコンフィギュレーションによって異なります。

AttributesManager

AttributesManagerには、ハンドラーで取得や更新を行えるアトリビュートがあります。AttributesManagerは、HandlerInputコンテナオブジェクトからハンドラーで使用できます。AttributesManagerは、スキルで必要なアトリビュートと直接やり取りできるよう、アトリビュートの取得と保存を行います。AttributesManagerの詳細については、TypeDocを参照してください。

利用可能なメソッド

getRequestAttributes() : {[key : string] : any};
getSessionAttributes() : {[key : string] : any};
getPersistentAttributes() : Promise<{[key : string] : any}>;
setRequestAttributes(requestAttributes : {[key : string] : any}) : void;
setSessionAttributes(sessionAttributes : {[key : string] : any}) : void;
setPersistentAttributes(persistentAttributes : {[key : string] : any}) : void;
savePersistentAttributes() : Promise<void>;
deletePersistentAttributes?() : Promise<void>;

以下は、永続アトリビュートの取得と保存を行う方法のサンプルです。

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

const PersistentAttributesHandler = {
  canHandle(handlerInput) {
    return new Promise((resolve, reject) => {
      handlerInput.attributesManager.getPersistentAttributes()
        .then((attributes) => {
          resolve(attributes.foo === 'bar');
        })
        .catch((error) => {
          reject(error);
        })
    });
  },
  handle(handlerInput) {
    return new Promise((resolve, reject) => {
      handlerInput.attributesManager.getPersistentAttributes()
        .then((attributes) => {
          attributes.foo = 'bar';
          handlerInput.attributesManager.setPersistentAttributes(attributes);

          return handlerInput.attributesManager.savePersistentAttributes();
        })
        .then(() => {
          resolve(handlerInput.responseBuilder
            .speak('永続アトリビュートが更新されました。')
            .getResponse());
        })
        .catch((error) => {
          reject(error);
        });
    });
  },
};

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

import {
  HandlerInput,
  RequestHandler,
} from 'ask-sdk-core';
import { Response } from 'ask-sdk-model';

const PersistentAttributesHandler : RequestHandler = {
  async canHandle(handlerInput : HandlerInput) : Promise<boolean> {
    const persistentAttributes = await  handlerInput.attributesManager.getPersistentAttributes();

    return persistentAttributes.foo === 'bar';

  },
  async handle(handlerInput : HandlerInput) : Promise<Response> {
    const persistentAttributes = await handlerInput.attributesManager.getPersistentAttributes();
    persistentAttributes.foo = 'bar';
    handlerInput.attributesManager.setPersistentAttributes(persistentAttributes);

    await handlerInput.attributesManager.savePersistentAttributes();

    return handlerInput.responseBuilder
      .speak('永続アトリビュートが更新されました。')
      .getResponse();
  },
};

PersistenceAdapter

PersistenceAdapterは、永続レイヤー(データベースやローカルファイルシステムなど)でアトリビュートを保存したり取得したりする場合にAttributesManagerが使用します。SDKを使用して、次のインターフェースに準拠する任意のカスタマイズ済みPersistenceAdapterを登録できます。

インターフェース

interface PersistenceAdapter {
  getAttributes(requestEnvelope : RequestEnvelope) : Promise<{[key : string] : any}>;
  saveAttributes(requestEnvelope : RequestEnvelope, attributes : {[key : string] : any}) : Promise<void>;
  deleteAttributes?(requestEnvelope : RequestEnvelope) : Promise<void>;
}

DynamoDbPersistenceAdapter

ask-sdk-dynamodb-persistence-adapterパッケージは、AWS DynamoDBを使ってPersistenceAdapterを実装したDynamoDbPersistenceAdapterを提供します。

コンストラクターの詳細

new DynamoDbPersistenceAdapter(config = {}) => Object

DynamoDbPersistenceAdapterオブジェクトを構築します。このオブジェクトは、アトリビュートオブジェクトのDynamoDBテーブルからの取得、保存、削除を行う際に、AttributesManagerによって使用されます。このテーブルには2つの列があります。1つはパーティションキー、1つはアトリビュートに使用されます。createTableコンフィギュレーションがtrueに設定されている場合にDynamoDbPersistenceAdapterがインスタンス化されると、SDKは指定されたtableNameで新しいDynamoDBテーブルを作成しようとします。

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

const { DynamoDbPersistenceAdapter } = require('ask-sdk-dynamodb-persistence-adapter');

const dynamoDbPersistenceAdapter = new DynamoDbPersistenceAdapter({ tableName : 'FooTable' })

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

import { PersistenceAdapter } from 'ask-sdk-core';
import { DynamoDbPersistenceAdapter } from 'ask-sdk-dynamodb-persistence-adapter';

const dynamoDbPersistenceAdapter : PersistenceAdapter = new DynamoDbPersistenceAdapter({ tableName : 'FooTable' });
コンフィギュレーションオプション
  • tableName(文字列) - 使用するDynamoDBテーブルの名前です。
  • partitionKeyName(文字列) - 任意です。パーティションキー列の名前です。指定されない場合、デフォルトの"id"になります。
  • attributesName(文字列) - 任意です。アトリビュート列の名前です。指定されない場合、デフォルトの"attributes"になります。
  • createTable(ブール値) - 任意です。trueに設定すると、テーブルが存在しない場合にDynamoDbPersistenceAdapterが自動で作成します。指定されない場合、デフォルトのfalseになります。
  • partitionKeyGenerator(関数) - 任意です。RequestEnvelopeを使ってパーティションキーを生成するときに使用される関数です。デフォルトでは、userIdを使ってパーティションキーを生成します。
  • dynamoDBClientAWS.DynamoDB) - 任意です。AWS DynamoDBテーブルのクエリーに使用するDynamoDBClientです。ここにカスタムコンフィギュレーションを使ったDynamoDBClientを挿入できます。デフォルトでは、new AWS.DynamoDB({apiVersion : 'latest'})が使用されます。

メソッドの詳細

getAttributes(requestEnvelope : RequestEnvelope) : Promise<{[key : string] : any}>
getAttributes操作により、DynamoDBテーブルからアトリビュートが取得されます。RequestEnvelopeオブジェクトを取り込んでPartitionKeyGeneratorに渡し、パーティションキーが生成されます。その後、attributesNameに関連したキーを持つDynamoDBから返されたアトリビュートを取得します。対応するパーティションキーが見つからない場合、getAttributesは空のオブジェクトを返します。
saveAttributes(requestEnvelope : RequestEnvelope, attributes : {[key : string] : any}) : Promise<void>
saveAttributes操作では、RequestEnvelopeから生成されたパーティションキーを使用してDynamoDBテーブルにアトリビュートを保存します。convertEmptyValuestrueに設定したDynamoDBDocumentClientを使用します。これは、アトリビュートオブジェクト内のすべての""nullundefinedの値が変換されるようにするためです。
deleteAttributes(requestEnvelope : RequestEnvelope) : Promise<void>
deleteAttributes操作では、RequestEnvelopeで生成されたパーティションキーを使用してDynamoDBテーブルからアトリビュートを削除します。この操作では、整合性を保つため、ローカルにキャッシュされた永続アトリビュートも消去します。該当するパーティションキーを持つアトリビュートがテーブルに存在しない場合、deleteAttributesは何も行いません。

S3PersistenceAdapter

ask-sdk-s3-persistence-adapterパッケージは、AWS S3を使ってPersistenceAdapterを実装したS3PersistenceAdapterを提供します。

コンストラクターの詳細

new S3PersistenceAdapter(config = {}) => Object

S3PersistenceAdapterオブジェクトを構築します。このオブジェクトは、アトリビュートオブジェクトを取得してS3バケットに保存するためにAttributesManagerによって使用されます。アトリビュートオブジェクトは、オブジェクトキーのファイル名を持つ個別のファイルとして表わされます。

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

const { S3PersistenceAdapter } = require('ask-sdk-s3-persistence-adapter');

const s3PersistenceAdapter = new S3PersistenceAdapter({ bucketName : 'FooBucket' })

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

import { PersistenceAdapter } from 'ask-sdk-core';
import { S3PersistenceAdapter } from 'ask-sdk-dynamodb-persistence-adapter';

const S3PersistenceAdapter : PersistenceAdapter = new S3PersistenceAdapter({ bucketName : 'FooBucket' });
コンフィギュレーションオプション
  • bucketName(文字列) - 使用するS3バケットの名前です。
  • objectKeyGenerator(関数) - 任意です。RequestEnvelopeを使ってオブジェクトキーを生成するために使用される関数です。デフォルトでは、userIdを使ってオブジェクトキーを生成します。
  • s3ClientAWS.S3) - 任意です。AWS S3バケットのクエリーに使用されるS3Clientです。ここにカスタムコンフィギュレーションを使ったS3Clientを挿入できます。デフォルトでは、new AWS.S3({apiVersion : 'latest'})が使用されます。
  • pathPrefix(文字列) - 生成されたオブジェクトキーに追加されるプレフィックスの値です。s3でファイルシステム構造を模倣するために使用されます。デフォルトは空の文字列です。

メソッドの詳細

getAttributes(requestEnvelope : RequestEnvelope) : Promise<{[key : string] : any}>
getAttributes操作により、S3バケットからアトリビュートが取得されます。RequestEnvelopeオブジェクトを取り込んでObjectKeyGeneratorに渡し、オブジェクトキーが生成されます。その後、S3バケットから返されたアトリビュートを取得します。対応するオブジェクトキーが見つからない場合、またはオブジェクトにbodyデータがない場合、getAttributesは空のオブジェクトを返します。
saveAttributes(requestEnvelope : RequestEnvelope, attributes : {[key : string] : any}) : Promise<void>
saveAttributes操作では、RequestEnvelopeで生成されたオブジェクトキーを使用してS3バケットにアトリビュートを保存します。
deleteAttributes(requestEnvelope : RequestEnvelope) : Promise<void>
deleteAttributes操作では、RequestEnvelopeで生成されたオブジェクトキーを使用してS3バケットからアトリビュートを削除します。