拡張子 - AWS AppSync
引数: filterJsonObject引数: invalidationJsonObject

拡張子

注記

現在、主に APPSYNC_JS ランタイムとそのドキュメントをサポートしています。こちら で APPSYNC_JS ランタイムとそのガイドの使用をご検討ください。

$extensions には、リゾルバー内で追加のアクションを行うためのメソッドセットが含まれています。

$extensions.evictFromApiCache(String, String, Object) : Object

AWS AppSync サーバー側のキャッシュからアイテムを削除します。最初の引数は型名です。2 番目の引数はフィールド名です。3 番目の引数は、キャッシュキー値を指定するキーと値のペア項目を含むオブジェクトです。オブジェクト内の項目は、キャッシュされたリゾルバー cachingKey のキャッシュキーと同じ順序で配置する必要があります。

注記

このユーティリティはミューテーションに対してのみ機能し、クエリには使用できません。

$extensions.setSubscriptionFilter(filterJsonObject)

強化されたサブスクリプションフィルターを定義します。各サブスクリプション通知イベントは、提供されたサブスクリプションフィルタに対して評価され、すべてのフィルタが true に評価された場合、クライアントに通知を配信します。引数は以下のセクションで説明するとおり filterJsonObject です。

注記

この拡張メソッドは、サブスクリプションリゾルバーのレスポンスマッピングテンプレートでのみ使用できます。

$extensions.setSubscriptionInvalidationFilter(filterJsonObject)

サブスクリプション無効化フィルターを定義します。サブスクリプションフィルタは無効化ペイロードに照らして評価されてから、フィルターが true と評価された場合、与えられたサブスクリプションを無効にします。引数は以下のセクションで説明するとおり filterJsonObject です。

注記

この拡張メソッドは、サブスクリプションリゾルバーのレスポンスマッピングテンプレートでのみ使用できます。

$extensions.invalidateSubscriptions(invalidationJsonObject)

ミューテーションによるサブスクリプションの無効化を開始するために使用されます。引数は以下のセクションで説明するとおり invalidationJsonObject です。

注記

この拡張関数はミューテーションリゾルバーのレスポンスマッピングテンプレートでのみ使用できます。

1 つのリクエストで使用できるユニークな $extensions.invalidateSubscriptions() メソッド呼び出しは 5 つまでです。この制限を超えた場合、GraphQL エラーが表示されます。

引数: filterJsonObject

JSON オブジェクトは、サブスクリプションフィルターまたは無効化フィルターのいずれかを定義します。これは、filterGroup 内のフィルターの配列です。各フィルターは個別のフィルターの集まりです。

{
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                }
           ]
           
        },
        {
           "filters" : [
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]
           
        }
    ]
}

各フィルターには次の 3 つの属性があります。

  • fieldName – GraphQL スキーマフィールド。

  • operator – オペレータータイプ。

  • value – サブスクリプション通知 fieldName 値と比較する値。

以下は、これらの属性の割り当ての例です。

{
 "fieldName" : "severity",
 "operator" : "le",
 "value" : $context.result.severity
}

フィールド: fieldName

文字列タイプ fieldName は、サブスクリプション通知ペイロード内の fieldName と一致する GraphQL スキーマで定義されているフィールドを指します。一致するものが見つかると、GraphQL スキーマフィールドの value がサブスクリプション通知フィルターのフィールドの value と比較されます。次の例では、fieldName フィルターは特定の GraphQL タイプで定義された service フィールドと一致します。通知ペイロードが AWS AppSync と等しい value のある service フィールドを含む場合、フィルタは true と評価されます：

{
 "fieldName" : "service",
 "operator" : "eq",
 "value" : "AWS AppSync"
}

フィールド: 値

値は演算子によって異なるタイプでもかまいません。

  • 1 つの数値またはブール値

    • 文字列型の例: "test"、"service"

    • 数値型の例:

    • ブール型の例:

  • 数字または文字列のペア

    • 文字列ペアの例: ["test1","test2"]、["start","end"]

    • 数値ペアの例: [1,4]、[67,89]、[12.45, 95.45]

  • 数値または文字列の配列

    • 文字列配列の例:["test1","test2","test3","test4","test5"]

    • 数値配列の例: [1,2,3,4,5]、[12.11,46.13,45.09,12.54,13.89]

フィールド演算子

大文字と小文字が区別される文字列で、以下の値を指定できます。

演算子 説明 可能な値型
eq Equal integer, float, string, Boolean
ne Not equal integer, float, string, Boolean
le Less than or equal integer, float, string
lt Less than integer, float, string
ge Greater than or equal integer, float, string
gt Greater than integer, float, string
contains Checks for a subsequence or value in the set. integer, float, string
notContains Checks for the absence of a subsequence or absence of a value in the set. integer, float, string
beginsWith Checks for a prefix. string
in Checks for matching elements that are in the list. Array of integer, float, or string
notIn Checks for matching elements that aren't in the list. Array of integer, float, or string
between Between two values integer, float, string
containsAny Contains common elements integer, float, string

次の表は、サブスクリプション通知での各オペレーターの使用法を示したものです。

eq (equal)

eq 演算子は、サブスクリプション通知フィールドの値がフィルターの値と一致し、厳密に等しいかどうかを true に対して評価します。次の例では、フィルターはサブスクリプション通知に AWS AppSync に等しい値の service フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列、ブール値

{
 "fieldName" : "service",
 "operator" : "eq",
 "value" : "AWS AppSync"
}
ne (not equal)

ne 演算子は、サブスクリプション通知フィールドの値がフィルターの値と異なるかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に AWS AppSync と異なる値の service フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列、ブール値

{
 "fieldName" : "service",
 "operator" : "ne",
 "value" : "AWS AppSync"
}
le (less or equal)

le 演算子は、サブスクリプション通知フィールドの値がフィルターの値以下かどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に5以下の値のsizeフィールドがあるかどうかをtrue に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列

{
 "fieldName" : "size",
 "operator" : "le",
 "value" : 5
}
lt (less than)

lt 演算子は、サブスクリプション通知フィールドの値がフィルターの値よりも小さいかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に 5 以下の値の size フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列

{
 "fieldName" : "size",
 "operator" : "lt",
 "value" : 5
}
ge (greater or equal)

ge 演算子は、true サブスクリプション通知フィールドの値がフィルターの値以上かどうかを評価します。次の例では、フィルターは、サブスクリプション通知に 5 以上の値の size フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列

{
 "fieldName" : "size",
 "operator" : "ge",
 "value" : 5
}
gt (greater than)

gt 演算子は、サブスクリプション通知フィールドの値がフィルターの値より大きいかどうかを に対して評価します。次の例では、フィルターは、サブスクリプション通知に 5 以上の値の size フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列

{
 "fieldName" : "size",
 "operator" : "gt",
 "value" : 5
}
contains

contains 演算子は、サブストリング、サブシーケンス、またはセットまたは単一アイテムをチェックします。contains 演算子を含むフィルターは、サブスクリプション通知フィールドの値にフィルタ値が含まれているかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に値 10 を含む配列値を持つ seats フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列

{
 "fieldName" : "seats",
 "operator" : "contains",
 "value" : 10
}

別の例として、フィルターはサブスクリプション通知にサブストリングとして launch を含む event フィールドがあるかどうかをtrue に対して評価します。

{
 "fieldName" : "event",
 "operator" : "contains",
 "value" : "launch"
}
notContains

notContains 演算子は、サブストリング、サブシーケンス、またはセットまたは値がないことをチェックします。notContains 演算子を使ったフィルターは、サブスクリプション通知フィールドの値にフィルタ値が含まれていないかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に値 10 を含まない配列値の seats フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点、文字列

{
 "fieldName" : "seats",
 "operator" : "notContains",
 "value" : 10
}

別の例として、フィルターはサブスクリプション通知のサブシーケンスとしての launch なしで event フィールド値があるかどうかを true に対して評価します。

{
 "fieldName" : "event",
 "operator" : "notContains",
 "value" : "launch"
}
beginsWith

beginsWith 演算子は文字列のプレフィックスをチェックします。beginsWith 演算子を含むフィルターは、サブスクリプション通知フィールドの値がフィルタの値で始まるかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に値がで始まる service フィールドがあるかどうかを true に対して評価します。

指定できる値の種類: 文字列

{
 "fieldName" : "service",
 "operator" : "beginsWith",
 "value" : "AWS"
}
in

in 演算子は配列内の一致する要素をチェックします。in 演算子を含むフィルタは、サブスクリプション通知フィールド値が配列に存在するかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に配列 [1,2,3] 内のいずれかの値を含む severity フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点数、または文字列の配列

{
 "fieldName" : "severity",
 "operator" : "in",
 "value" : [1,2,3]
}
notIn

notIn 演算子は配列に欠けている要素がないかチェックします。notIn 演算子を含むフィルタは、サブスクリプション通知フィールド値が配列に存在しないかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に、配列 [1,2,3] に存在しない値のいずれかを含む severity フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点数、または文字列の配列

{
 "fieldName" : "severity",
 "operator" : "notIn",
 "value" : [1,2,3]
}
between

between 演算子は 2 つの数値または文字列の間の値をチェックします。between 演算子を含むフィルターは、サブスクリプション通知フィールドの値がフィルタの値ペアの間にあるかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知に値 2、3、4 を含む severity フィールドがあるかどうかを true に対して評価します。

指定できる値のタイプ: 整数、浮動小数点数、または文字列のペア

{
 "fieldName" : "severity",
 "operator" : "between",
 "value" : [1,5]
}
containsAny

containsAny 演算子は配列内の共通要素をチェックします。containsAny 演算子を使ったフィルタ＝は、サブスクリプション通知フィールドの設定値とフィルタセット値の共通部分が空でないかどうかを true に対して評価します。次の例では、フィルターは、サブスクリプション通知にまたはを含む配列値を持つ seats フィールドがあるかどうかをtrueに対して評価します。つまり、フィルターは、サブスクリプション通知の [15,20,30] フィールド値が true または seats であるかどうかを [10,11] に対して評価します。

指定できる値のタイプ: 整数、浮動小数点数、または文字列

{
 "fieldName" : "seats",
 "operator" : "containsAny",
 "value" : [10, 15]
}

AND ロジック

filterGroup 配列内の filters オブジェクト内に複数のエントリを定義することで、AND ロジックを使用して複数のフィルターを組み合わせることができます。次の例では、フィルターは、サブスクリプション通知にフィールドの値が等しく、userId フィールド値が 1 または group のいずれかであるかどうかを true に対して評価します。

{
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                },
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]
           
        }
    ]
}

OR ロジック

filterGroup 配列内に複数のフィルターオブジェクトを定義することで、OR ロジックを使用して複数のフィルターを組み合わせることができます。次の例では、フィルターは、サブスクリプション通知に Admin OR Developer と同等の値の userId フィールドがあるかどうか、1 またはの group フィールド値があるかどうかを true に対して評価します。

{
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                }
           ]
           
        },
        {
           "filters" : [
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]
           
        }
    ]
}

例外

フィルターの使用にはいくつかの制限があることに注意してください。

  • filters オブジェクトには、フィルターごとに最大 5 つのユニークな fieldName 項目を設定できます。つまり、AND ロジックを使用して最大 5 つの個別の fieldName オブジェクトを組み合わせることができます。

  • containsAny 演算子には最大 20 個の値を指定できます。

  • in and notIn 演算子には最大 5 つの値を指定できます。

  • 接続文字列は最大 255 文字です。

  • 文字列比較では、大文字と小文字を区別します。

  • ネストされたオブジェクトフィルタリングでは、最大 5 つのネストレベルのフィルタリングが可能です。

  • filterGroup にはそれぞれ、最大 10 個 filters 設定できます。つまり、OR ロジックを使用して最大 10 個 filters を組み合わせることができます。

    • in 演算子は OR ロジックの特殊なケースです。次の例には、次の 2 つの filters があります。

      {
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                },
                {
                    "fieldName" : "group",
                    "operator" : "in",
                    "value" : ["Admin", "Developer"]
                }
           ]  
        }
    ]
}

      前述のフィルターグループは次のように評価され、最大フィルター制限に加算されます。

      {
    "filterGroup": [
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                },
                {
                    "fieldName" : "group",
                    "operator" : "eq",
                    "value" : "Admin"
                }
           ]  
        },
        {
           "filters" : [
                 {
                    "fieldName" : "userId",
                    "operator" : "eq",
                    "value" : 1
                },
                {
                    "fieldName" : "group",
                    "operator" : "eq",
                    "value" : "Developer"
                }
           ]  
        }
    ]
}

引数: invalidationJsonObject

invalidationJsonObject では以下が定義されます。

  • subscriptionField – 無効にする GraphQL スキーマのサブスクリプション。subscriptionFieldで文字列として定義されている 1 つのサブスクリプションは無効とみなされます。

  • payload — 無効化フィルターがその値に対して true と評価された場合に、サブスクリプションを無効化するための入力として使用されるキーと値のペアリスト。

    以下の例では、サブスクリプションリゾルバーで定義された無効化フィルターが payload 値に対して true と評価されたとき、onUserDelete サブスクリプションを使用してサブスクライブして接続しているクライアントを無効にします。

    $extensions.invalidateSubscriptions({
        "subscriptionField": "onUserDelete",
        "payload": {
                "group": "Developer"
                "type" : "Full-Time"
      }
    })