スキルのアトリビュート
このガイドでは、スキル開発に使用できるアトリビュートのさまざまなスコープと、スコープをスキルで使用する方法について説明します。
アトリビュート
SDKを使うと、さまざまなスコープでアトリビュートの保存と取得が可能になります。たとえば、アトリビュートを使用して後続のリクエストで取得するデータを保存できます。また、ハンドラーのcan_handleロジックでアトリビュートを使用して、リクエストのルーティングに条件を追加することもできます。
アトリビュートは、キーと値で構成されます。キーはStr型限定、値は無制限のobject型です。セッションアトリビュートと永続アトリビュートの場合、値は保存して後で取得できるよう、シリアライズできるデータ型である必要があります。この制限はリクエストレベルのアトリビュートには適用されません。なぜならリクエストレベルのアトリビュートは、リクエスト処理のライフサイクルが終了すると、永続的に存在しないからです。
アトリビュートのスコープ
リクエストアトリビュート
リクエストアトリビュートは、1回のリクエスト処理ライフサイクルの間のみ存続します。リクエストを受信した時点では、リクエストアトリビュートは空です。また応答が生成されると破棄されます。
リクエストアトリビュートは、リクエストと応答のインターセプターと合わせて使うと便利です。たとえば、リクエストインターセプターを使って追加のデータとヘルパーメソッドをリクエストアトリビュートに挿入して、リクエストハンドラーが取得できるようにできます。
セッションアトリビュート
セッションアトリビュートは、現在のスキルセッションが継続している間存続します。セッションアトリビュートは、すべてのセッション内リクエストで使用できます。リクエスト処理のライフサイクル中に設定されたすべてのアトリビュートはAlexaサービスに返され、同じセッションの次のリクエストで提供されます。
セッションアトリビュートで、外部ストレージソリューションを使用する必要はありません。セッションアトリビュートはセッション外のリクエストの処理では使用できません。スキルセッションがクローズされると破棄されます。
ask_sdk_model.request_envelope.RequestEnvelopeおよびask_sdk_model.response_envelope.ResponseEnvelopeオブジェクトのsessionプロパティに保存されるため、シリアル化可能な型のみをそれらの下に保存できます。ask_sdk_core.serialize.DefaultSerializerは値をシリアル化／逆シリアル化するために使用されます。永続アトリビュート
永続アトリビュートは、現在のセッションのライフサイクルが終了しても存続します。主要なスコープ（ユーザーID、デバイスID）、TTL、ストレージレイヤーを含む、これらのアトリビュートがどのように保存されるかはスキルのコンフィギュレーションによって異なります。
PersistenceAdapterを使用してスキルのインスタンスを設定する場合にのみ使用できます。PersistenceAdapterが設定されていない場合に、AttributesManagerを呼び出して永続アトリビュートの取得と保存を行おうとするとエラーが発生します。AttributesManager
AttributesManagerには、ハンドラーで取得や更新を行えるアトリビュートがあります。AttributesManagerは、Handler Inputオブジェクトからハンドラーで使用できます。AttributesManagerは、スキルで必要なアトリビュートと直接やり取りできるように、アトリビュートの取得と保存を行います。
インターフェース
class AttributesManager(object):
def __init__(self, request_envelope, persistence_adapter=None):
# type: (RequestEnvelope, AbstractPersistenceAdapter) -> None
....
@property
def request_attributes(self):
# type: () -> Dict[str, Any]
# Request Attributes getter
....
@request_attributes.setter
def request_attributes(self, attributes):
# type: (Dict[str, Any]) -> None
# Request Attributes setter
....
@property
def session_attributes(self):
# type: () -> Dict[str, Any]
# Session Attributes getter
....
@session_attributes.setter
def session_attributes(self, attributes):
# type: (Dict[str, Any]) -> None
# Session Attributes setter
....
@property
def persistent_attributes(self):
# type: () -> Dict[str, Any]
# Persistence Attributes getter
# Uses the Persistence adapter to get the attributes
....
@persistent_attributes.setter
def persistent_attributes(self, attributes):
# type: (Dict[str, Any]) -> None
# Persistent Attributes setter
....
def save_persistent_attributes(self):
# type: () -> None
# 永続アトリビュートを永続レイヤーに保存します
....
def delete_persistent_attributes(self):
# type: () -> None
# 永続アトリビュートを永続レイヤーから削除します
....
以下は、永続アトリビュートの取得と保存を行う方法のサンプルです。
class PersistenceAttributesHandler(AbstractRequestHandler):
def can_handle(handler_input):
persistence_attr = handler_input.attributes_manager.persistent_attributes
return persistence_attr['foo'] == 'bar'
def handle(handler_input):
persistence_attr = handler_input.attributes_manager.persistent_attributes
persistence_attr['foo'] = 'baz'
handler_input.attributes_manager.save_persistent_attributes()
return handler_input.response_builder.response
AttributesManagerは永続アトリビュートをローカルにキャッシュします。setPersistentAttributes()は、ローカルにキャッシュされた永続アトリビュートのみを更新します。永続アトリビュートを永続レイヤーに保存するには、savePersistentAttributes()を呼び出す必要があります。DynamoDbPersistenceAdapter実装のdelete_attributesは、ローカルキャッシュおよび永続レイヤー（DynamoDBテーブル）から永続アトリビュートを削除します。PersistenceAdapter
AbstractPersistenceAdapterは、永続レイヤー（データベースやローカルファイルシステムなど）でアトリビュートを保存したり取得したりする場合にAttributesManagerが使用します。SDKを使用して、AbstractPersistenceAdapterインターフェースに準拠する任意のカスタマイズ済みPersistenceAdapterを登録できます。
AbstractPersistenceAdapterの実装はすべて、以下のインターフェースに従う必要があります。
インターフェース
class AbstractPersistenceAdapter(object):
def get_attributes(self, request_envelope):
# type: (RequestEnvelope) -> Dict[str, Any]
pass
def save_attributes(self, request_envelope, attributes):
# type: (RequestEnvelope, Dict[str, Any]) -> None
pass
DynamoDBPersistenceAdapter
ask-sdk-dynamodb-persistence-adapterパッケージは、AWS DynamoDBを使用してAbstractPersistenceAdapterを実装します。
インターフェース
from ask_sdk_dynamodb.adapter import DynamoDbAdapter
adapter = DynamoDbAdapter(table_name, partition_key_name="id",
attribute_name="attributes", create_table=False,
partition_keygen=user_id_partition_keygen,
dynamodb_resource=boto3.resource("dynamodb")
コンフィギュレーションオプション
- table_name（文字列） - 使用するDynamoDBテーブルの名前です。
- partition_key_name（文字列） - 任意です。パーティションキー列の名前です。指定されない場合、デフォルトの
"id"になります。 - attributes_name（文字列） - 任意です。アトリビュート列の名前です。指定されない場合、デフォルトの
attributesになります。 - create_table（ブール値） - 任意です。
Trueに設定すると、テーブルが存在しない場合にDynamoDbAdapterが自動で作成します。指定されない場合、デフォルトのFalseになります。 - partition_keygen（呼び出し可能） - 任意です。
RequestEnvelopeを使ってパーティションキーを生成するときに使用される関数です。デフォルトでは、user_idを使用してパーティションキーを生成します。 - dynamodb_resource（AWS.DynamoDB ServiceResource） - 任意です。AWS DynamoDBテーブルのクエリーに使用する
DynamoDBClientです。ここにカスタムコンフィギュレーションを使ったDynamoDBClientを挿入できます。デフォルトではboto3.resource("dynamodb")を使用します。
詳細については、DynamoDB永続アダプターを参照してください。
S3PersistenceAdapter
ask-sdk-s3-persistence-adapterパッケージは、 Amazon S3を使用してAbstractPersistenceAdapterを実装します。
インターフェース
*from** *ask_sdk_s3.adapter *import** *S3Adapter
*from** *ask_sdk_core.skill_builder *import** *CustomSkillBuilder
s3_client = boto3.client(*'s3'*)
s3_adapter = S3Adapter(bucket_name="bucket_name",
path_prefix=*"path/prefix"*, s3_client=s3_client, object_keygen=user_id_keygen)
sb = CustomSkillBuilder(persistence_adapter=s3_adapter)
コンフィギュレーションオプション
- bucket_name（文字列）- 使用するS3バケットの名前です。
- path_prefix（文字列） - 任意です。オブジェクトのS3パスプレフィックスです。指定されない場合、デフォルトの接頭辞なしになります。
- s3_client（S3.Client） - 任意です。S3クライアントは、Amazon S3を表します。指定されたS3バケットの保存、取得、削除を行うシンプルなインターフェースを提供します。ここにカスタムコンフィギュレーションを使ったS3クライアントを挿入できます。クライアントのデフォルトはboto3.client('s3')を使用します。
- object_keygen（文字列） - 任意です。
RequestEnvelopeを使用してオブジェクトキーを生成する関数です。デフォルトの動作は、user_idを使用してオブジェクトキーを生成します。
詳細については、S3永続性アダプターを参照してください。