アトリビュートの管理
SDKを使うと、さまざまなスコープでアトリビュートの保存と取得が可能になります。たとえば、アトリビュートを使って後続のリクエストで取得するデータを保存できます。また、ハンドラーのcanHandleロジックでアトリビュートを使うことで、リクエストのルーティングに影響を与えることも可能です。
アトリビュートは、キーと値で構成されます。キーはString型で強制型、値は無制限のObject型です。セッションアトリビュートと永続アトリビュートの場合、値は保存して後で取得できるよう、シリアライズできるデータ型である必要があります。この制限はリクエストレベルのアトリビュートには適用されません。なぜならリクエストレベルのアトリビュートは、リクエスト処理のライフサイクルが終了すると、永続的に存在しないからです。
アトリビュートのスコープ
リクエストアトリビュート
リクエストアトリビュートは、1回のリクエスト処理ライフサイクルの間のみ存続します。リクエストを受信した時点では、リクエストアトリビュートは空です。また応答が生成されると破棄されます。
リクエストアトリビュートは、リクエストと応答のインターセプターと合わせて使うと便利です。たとえば、リクエストインターセプターを使って追加のデータとヘルパークラスをリクエストアトリビュートに挿入して、リクエストハンドラーから取得できるようにすることが可能です。
セッションアトリビュート
セッションアトリビュートは、現在のスキルセッションが継続している間存続します。セッションアトリビュートは、すべてのセッション内リクエストで使用できます。リクエスト処理のライフサイクル中に設定されたすべてのアトリビュートはAlexaサービスに返され、同じセッションの次のリクエストで提供されます。
セッションアトリビュートで、外部ストレージソリューションを使用する必要はありません。セッションアトリビュートはセッション外のリクエストの処理では使用できません。スキルセッションがクローズされると破棄されます。
永続アトリビュート
永続アトリビュートは、現在のセッションのライフサイクルが終了しても存続します。主要なスコープ（ユーザーID、デバイスID）、TTL、ストレージレイヤーを含む、これらのアトリビュートがどのように保存されるかは、PersistenceAdapterのコンフィギュレーションによって異なります。
PersistenceAdapterを使用してスキルのインスタンスを設定する場合にのみ使用できます。PersistenceAdapterが設定されていない場合に、AttributesManagerを呼び出して永続アトリビュートの取得と保存を行おうとするとエラーが発生します。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();
},
};
AttributesManagerは永続アトリビュートをローカルにキャッシュします。setPersistentAttributes()は、ローカルにキャッシュされた永続アトリビュートのみを更新します。永続アトリビュートを永続レイヤーに保存するには、savePersistentAttributes()を呼び出す必要があります。deletePersistentAttributes()を呼び出すと、ローカルにキャッシュされた永続アトリビュートも削除されます。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を使ってパーティションキーを生成します。 - dynamoDBClient（AWS.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テーブルにアトリビュートを保存します。convertEmptyValuesをtrueに設定したDynamoDBDocumentClientを使用します。これは、アトリビュートオブジェクト内のすべての""、null、undefinedの値が変換されるようにするためです。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を使ってオブジェクトキーを生成します。 - s3Client（AWS.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バケットからアトリビュートを削除します。