本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 延伸模組 **注意** 我們現在主要支援 APPSYNC\$1JS 執行期及其文件。請考慮[在此處](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-reference-js-version.html)使用 APPSYNC\$1JS 執行期及其指南。 `$extensions` 包含一組方法，可在解析程式中執行其他動作。 ## 快取擴充功能 **`$extensions.evictFromApiCache(String, String, Object) : Object`** 從 AWS AppSync 伺服器端快取中移出項目。第一個引數是類型名稱。第二個引數是欄位名稱。第三個引數是包含金鑰值對項目的物件，可指定快取金鑰值。您必須以與快取解析程式 中的快取金鑰相同的順序，將項目放在物件中`cachingKey`。 此公用程式僅適用於變動，不適用於查詢。 ## 訂閱擴充功能 **`$extensions.setSubscriptionFilter(filterJsonObject)`** 定義增強型訂閱篩選條件。每個訂閱通知事件都會根據提供的訂閱篩選條件進行評估，並在所有篩選條件評估為 時傳送通知給用戶端`true`。引數`filterJsonObject`如下節所述。 您只能在訂閱解析程式的回應映射範本中使用此延伸方法。 **`$extensions.setSubscriptionInvalidationFilter(filterJsonObject)`** 定義訂閱失效篩選條件。系統會針對失效承載評估訂閱篩選條件，如果篩選條件評估為 ，則會使指定的訂閱失效`true`。引數`filterJsonObject`如下節所述。 您只能在訂閱解析程式的回應映射範本中使用此延伸方法。 **`$extensions.invalidateSubscriptions(invalidationJsonObject)`** 用來從變動啟動訂閱失效。引數`invalidationJsonObject`如下節所述。 此延伸模組只能用於變動解析程式的回應映射範本。 在任何單一請求中，您最多只能使用五個唯一的`$extensions.invalidateSubscriptions()`方法呼叫。如果您超過此限制，您將會收到 GraphQL 錯誤。 ## 引數：filterJsonObject JSON 物件會定義訂閱或失效篩選條件。這是 中的一系列篩選條件`filterGroup`。每個篩選條件都是個別篩選條件的集合。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` 每個篩選條件都有三個屬性： + `fieldName` – GraphQL 結構描述欄位。 + `operator` – 運算子類型。 + `value` – 要與訂閱通知值比較`fieldName`的值。 以下是這些屬性的範例指派： ``` { "fieldName" : "severity", "operator" : "le", "value" : $context.result.severity } ``` ### 欄位：fieldName 字串類型`fieldName`是指在 GraphQL 結構描述中定義的欄位，符合訂閱通知承載`fieldName`中的 。找到相符項目時，GraphQL 結構描述欄位`value`的 會與訂閱通知篩選條件`value`的 進行比較。在下列範例中，`fieldName`篩選條件符合指定 GraphQL 類型中定義的`service`欄位。如果通知承載包含等於 `value` `service`的欄位`AWS AppSync`，則篩選條件會評估為 `true`： ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ### 欄位：值 根據運算子，值可以是不同的類型： + 單一數字或布林值 + 字串範例：`"test"`、 `"service"` + 數字範例：`1`、`2`、 `45.75` + 布林值範例：`true`、 `false` + 一組數字或字串 + 字串對範例：`["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]` ### 欄位：運算子 具有下列可能值的區分大小寫字串： | | | 運算子 | Description | 可能的值類型 | | --- |--- |--- | | 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) ] 如果`true`訂閱通知欄位值相符且嚴格等於篩選條件的值，則`eq`運算子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值等於 `service`的欄位`AWS AppSync`。 **可能的值類型：**整數、浮點數、字串、布林值 ``` { "fieldName" : "service", "operator" : "eq", "value" : "AWS AppSync" } ``` ------ #### [ ne (not equal) ] 如果`true`訂閱通知欄位值與篩選條件的值不同，運算`ne`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值與 不同的`service`欄位`AWS AppSync`。 **可能的值類型：**整數、浮點數、字串、布林值 ``` { "fieldName" : "service", "operator" : "ne", "value" : "AWS AppSync" } ``` ------ #### [ le (less or equal) ] 如果`true`訂閱通知欄位值小於或等於篩選條件的值，`le`運算子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值小於或等於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "le", "value" : 5 } ``` ------ #### [ lt (less than) ] 如果`true`訂閱通知欄位值低於篩選條件的值，運算`lt`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值低於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "lt", "value" : 5 } ``` ------ #### [ ge (greater or equal) ] 如果`true`訂閱通知欄位值大於或等於篩選條件的值，運算`ge`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值大於或等於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "ge", "value" : 5 } ``` ------ #### [ gt (greater than) ] 如果`true`訂閱通知欄位值大於篩選條件的值，運算`gt`子會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值大於 `size`的欄位`5`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "size", "operator" : "gt", "value" : 5 } ``` ------ #### [ contains ] `contains` 運算子會檢查集合或單一項目中的子字串、子序列或值。如果訂閱通知欄位值包含篩選條件值，則具有 `contains` 運算子的篩選條件會評估`true`為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有`seats`欄位的陣列值包含值 `10`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "seats", "operator" : "contains", "value" : 10 } ``` 在另一個範例中，篩選條件會評估訂閱通知`true`是否具有 `launch`做為子字串`event`的欄位。 ``` { "fieldName" : "event", "operator" : "contains", "value" : "launch" } ``` ------ #### [ notContains ] `notContains` 運算子會檢查集合或單一項目中是否存在子字串、子序列或值。如果訂閱通知欄位值不包含篩選條件值`true`，則具有 `notContains` 運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否具有陣列值不包含值 `seats`的欄位`10`。 **可能的值類型：**整數、浮點數、字串 ``` { "fieldName" : "seats", "operator" : "notContains", "value" : 10 } ``` 在另一個範例中，篩選條件會評估訂閱通知`true`是否具有 `launch`作為其子序列的 `event` 欄位值。 ``` { "fieldName" : "event", "operator" : "notContains", "value" : "launch" } ``` ------ #### [ beginsWith ] `beginsWith` 運算子會檢查字串中的字首。如果訂閱通知欄位值以篩選條件的值開頭`true`，則包含`beginsWith`運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有值開頭為 `service`的欄位`AWS`。 **可能的值類型：**字串 ``` { "fieldName" : "service", "operator" : "beginsWith", "value" : "AWS" } ``` ------ #### [ in ] `in` 運算子會檢查陣列中的相符元素。如果訂閱通知欄位值存在於陣列中`true`，包含 `in` 運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有`severity`欄位具有陣列中存在的其中一個值：`[1,2,3]`。 **可能的值類型：**整數陣列、浮點數或字串 ``` { "fieldName" : "severity", "operator" : "in", "value" : [1,2,3] } ``` ------ #### [ notIn ] `notIn` 運算子會檢查陣列中是否有遺失的元素。如果訂閱通知欄位值不存在於陣列中`true`，則包含`notIn`運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否有`severity`欄位，其中包含陣列中不存在的其中一個值：`[1,2,3]`。 **可能的值類型：**整數陣列、浮點數或字串 ``` { "fieldName" : "severity", "operator" : "notIn", "value" : [1,2,3] } ``` ------ #### [ between ] `between` 運算子會檢查兩個數字或字串之間的值。如果訂閱通知欄位值介於篩選條件的值對之間`true`，則包含`between`運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否具有值為 `2`、`3`、 `severity`的欄位`4`。 **可能的值類型：**整數、浮點數或字串的配對 ``` { "fieldName" : "severity", "operator" : "between", "value" : [1,5] } ``` ------ #### [ containsAny ] `containsAny` 運算子會檢查陣列中的常見元素。如果訂閱通知欄位集值和篩選條件集值的交集不是空的`true`，則具有 `containsAny` 運算子的篩選條件會評估為 。在下列範例中，篩選條件會評估訂閱通知`true`是否具有陣列值包含 `10`或 `seats`的欄位`15`。這表示`true`如果訂閱通知`seats`的欄位值為 `[10,11]`或 ，篩選條件會評估為 `[15,20,30]`。 **可能的值類型：**整數、浮點數或字串 ``` { "fieldName" : "seats", "operator" : "containsAny", "value" : [10, 15] } ``` ------ ### AND 邏輯 您可以使用 AND 邏輯結合多個篩選條件，方法是在`filterGroup`陣列中的 `filters` 物件中定義多個項目。在下列範例中，篩選條件會評估訂閱通知`true`是否有 欄位`userId`的值等於 `1` AND `group` 欄位值 `Admin`或 `Developer`。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 }, { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### OR 邏輯 您可以在`filterGroup`陣列中定義多個篩選條件物件，以使用 OR 邏輯結合多個篩選條件。在下列範例中，篩選條件會評估訂閱通知`true`是否有欄位`userId`的值等於 `1` OR `group` 欄位值 `Admin`或 `Developer`。 ``` { "filterGroup": [ { "filters" : [ { "fieldName" : "userId", "operator" : "eq", "value" : 1 } ] }, { "filters" : [ { "fieldName" : "group", "operator" : "in", "value" : ["Admin", "Developer"] } ] } ] } ``` ### 例外狀況 請注意，使用篩選條件有幾項限制： + 在 `filters` 物件中，每個篩選條件最多可以有五個唯一`fieldName`項目。這表示您最多可以使用 AND 邏輯結合五個個別`fieldName`物件。 + 運算`containsAny`子最多可有 20 個值。 + `in` 和 `notIn`運算子最多可有五個值。 + 每個字串最多可有 256 個字元。 + 每個字串比較都區分大小寫。 + 巢狀物件篩選最多允許五個巢狀層級的篩選。 + 每個 `filterGroup` 最多可有 10 個 `filters`。這表示您可以使用 `filters` OR 邏輯結合最多 10 個。 + `in` 運算子是 OR 邏輯的特殊案例。在下列範例中，有兩個 `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`會被視為失效。 + `payload` – 金鑰/值對清單，當失效篩選條件`true`根據其值評估為 時，此清單會做為使訂閱失效的輸入。 當訂閱解析程式中定義的失效篩選條件`true`針對 `payload`值評估為 時，下列範例會使用`onUserDelete`訂閱使已訂閱和已連線的用戶端失效。 ``` $extensions.invalidateSubscriptions({ "subscriptionField": "onUserDelete", "payload": { "group": "Developer" "type" : "Full-Time" } }) ```