本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# AWS AppSync JavaScript 解析程式概觀
<a name="resolver-reference-overview-js"></a>

AWS AppSync 可讓您透過對資料來源執行操作來回應 GraphQL 請求。對於您想要執行查詢、變動或訂閱的每個 GraphQL 欄位，必須連接解析程式。

解析程式是 GraphQL 和資料來源之間的連接器。他們 tell AWS AppSync 如何將傳入的 GraphQL 請求轉譯為後端資料來源的指示，以及如何將來自該資料來源的回應轉譯回 GraphQL 回應。透過 AWS AppSync，您可以使用 JavaScript 撰寫解析程式，並在 AWS AppSync (`APPSYNC_JS`) 環境中執行。

AWS AppSync 可讓您撰寫由管道中多個 AWS AppSync 函數組成的單位解析程式或管道解析程式。

## 支援的執行時間功能
<a name="runtime-support-js"></a>

 AWS AppSync JavaScript 執行時間提供 JavaScript 程式庫、公用程式和功能的子集。如需`APPSYNC_JS`執行時間支援的完整功能清單，請參閱[解析程式和函數的 JavaScript 執行時間功能](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html)。

## 單位解析程式
<a name="unit-resolver-js"></a>

單位解析程式由程式碼組成，可定義針對資料來源執行的請求和回應處理常式。請求處理常式會將內容物件做為引數，並傳回用來呼叫資料來源的請求承載。回應處理常式會從資料來源接收承載，其中包含執行請求的結果。回應處理常式會將承載轉換為 GraphQL 回應，以解析 GraphQL 欄位。在下列範例中，解析程式會從 DynamoDB 資料來源擷取項目：

```
import * as ddb from '@aws-appsync/utils/dynamodb'

export function request(ctx) {
  return ddb.get({ key: { id: ctx.args.id } });
}

export const response = (ctx) => ctx.result;
```

## JavaScript 管道解析程式的剖析
<a name="anatomy-of-a-pipeline-resolver-js"></a>

管道解析程式由程式碼組成，可定義請求和回應處理常式，以及函數清單。每個函數都有一個針對資料來源執行的**請求**和**回應**處理常式。由於管道解析程式委派會執行到函數清單，因此不會連結到任何資料來源。單位解析程式和函數是對資料來源執行操作的基本元素。

### 管道解析程式請求處理常式
<a name="request-handler-js"></a>

管道解析程式的請求處理常式 （步驟前） 可讓您在執行定義的函數之前執行一些準備邏輯。

### 函數清單
<a name="functions-list-js"></a>

管道解析程式將會依序執行的函數清單。管道解析程式請求處理常式評估結果會以 的形式提供給第一個函數`ctx.prev.result`。每個函數評估結果都以 的形式提供給下一個函數`ctx.prev.result`。

### 管道解析程式回應處理常式
<a name="response-handler-js"></a>

管道解析程式的回應處理常式可讓您執行從最後一個函數輸出到預期 GraphQL 欄位類型的一些最終邏輯。函數清單中最後一個函數的輸出可在管道解析程式回應處理常式中作為 `ctx.prev.result`或 使用`ctx.result`。

### 執行流程
<a name="execution-flow-js"></a>

假設管道解析程式包含兩個函數，以下清單代表呼叫解析程式時的執行流程：

1.  管道解析程式請求處理常式

1.  函數 1：函數請求處理常式 

1.  第 1 個函數：資料來源呼叫 

1.  函數 1：函數回應處理常式 

1.  函數 2：函數請求處理常式 

1.  第 2 個函數：資料來源呼叫 

1.  函數 2：函數回應處理常式 

1.  管道解析程式回應處理常式 

![](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/appsync-js-resolver-logic.png)


### 實用的`APPSYNC_JS`執行期內建公用程式
<a name="useful-utilities-js"></a>

下列公用程式可在您使用管道解析程式時提供協助。

#### ctx.stash
<a name="ctx-stash-js"></a>

停滯是在每個解析程式和函數請求和回應處理常式中可用的物件。相同的 stash 執行個體透過單一解析程式執行運作。這表示您可以使用 stash 跨請求和回應處理常式，以及管道解析程式中的函數傳遞任意資料。您可以像一般 JavaScript 物件一樣測試堆疊。

#### ctx.prev.result
<a name="ctx-prev-result-js"></a>

`ctx.prev.result` 會顯示管道先前執行操作的結果。如果先前的操作是管道解析程式請求處理常式，則 `ctx.prev.result` 可供鏈結中的第一個函數使用。如果先前操作是第一個函數，則 `ctx.prev.result` 會顯示第一個函數的輸出，並將資料提供給管道中的第二個函數。如果先前的操作是最後一個函數，則 `ctx.prev.result` 代表最後一個函數的輸出，並可供管道解析程式回應處理常式使用。

#### util.error
<a name="util-error-js"></a>

`util.error` 公用程式非常適合用來擲出欄位錯誤。在函數請求或回應處理常式`util.error`內使用 會立即擲回欄位錯誤，以防止後續函數執行。如需詳細資訊和其他`util.error`簽章，請造訪[解析程式和函數的 JavaScript 執行期功能](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html)。

#### util.appendError
<a name="util-appenderror-js"></a>

`util.appendError` 類似於 `util.error()`，主要區別在於它不會中斷處理常式的評估。相反地，它表示 欄位發生錯誤，但允許評估處理常式並因此傳回資料。在函數中使用 `util.appendError` 並不會中斷管道的執行流程。如需詳細資訊和其他`util.error`簽章，請造訪[解析程式和函數的 JavaScript 執行期功能](https://docs.aws.amazon.com/appsync/latest/devguide/resolver-util-reference-js.html)。

#### runtime.earlyReturn
<a name="runtime-earlyreturn-js"></a>

`runtime.earlyReturn` 函數可讓您從任何請求函數提早傳回 。在解析程式請求處理常式`runtime.earlyReturn`內部使用 會從解析程式傳回 。從函數 AWS AppSync 請求處理常式呼叫它會從函數傳回，並繼續執行到管道中的下一個函數或解析程式回應處理常式。

### 撰寫管道解析程式
<a name="writing-resolvers"></a>

管道解析程式也有一個請求和一個回應處理常式，圍繞管道中函數的執行：其請求處理常式在第一個函數的請求之前執行，而其回應處理常式在最後一個函數的回應之後執行。解析程式請求處理常式可以設定要供管道中的函數使用的資料。解析程式回應處理常式負責傳回映射至 GraphQL 欄位輸出類型的資料。在下列範例中，解析程式請求處理常式會定義 `allowedGroups`；傳回的資料應屬於其中一個群組。此值可供解析程式的 函數用來請求資料。解析程式的回應處理常式會執行最終檢查並篩選結果，以確保只會傳回屬於允許群組的項目。

```
import { util } from '@aws-appsync/utils';

/**
 * Called before the request function of the first AppSync function in the pipeline.
 *  @param ctx the context object holds contextual information about the function invocation.
 */
export function request(ctx) {
  ctx.stash.allowedGroups = ['admin'];
  ctx.stash.startedAt = util.time.nowISO8601();
  return {};
}
/**
 * Called after the response function of the last AppSync function in the pipeline.
 * @param ctx the context object holds contextual information about the function invocation.
 */
export function response(ctx) {
  const result = [];
  for (const item of ctx.prev.result) {
    if (ctx.stash.allowedGroups.indexOf(item.group) > -1) result.push(item);
  }
  return result;
}
```

#### 撰寫 AWS AppSync 函數
<a name="writing-functions"></a>

AWS AppSync 函數可讓您撰寫常見邏輯，以便在結構描述中的多個解析程式之間重複使用。例如，您可以有一個稱為 `QUERY_ITEMS` 的 AWS AppSync 函數，負責從 Amazon DynamoDB 資料來源查詢項目。對於您要查詢項目的解析程式，只需將 函數新增至解析程式的管道，並提供要使用的查詢索引。邏輯不需要重新實作。

## 補充主題
<a name="supplemental-topics"></a>

**主題**
+ [使用 Amazon DynamoDB 的範例管道解析程式](https://docs.aws.amazon.com/appsync/latest/devguide/writing-code.html)
+ [設定`APPSYNC_JS`執行時間的公用程式](https://docs.aws.amazon.com/appsync/latest/devguide/utility-resolvers.html)
+ [`APPSYNC_JS`執行時間的綁定、TypeScript 和來源映射](https://docs.aws.amazon.com/appsync/latest/devguide/additional-utilities.html)
+ [測試您的解析程式和函數處理常式](https://docs.aws.amazon.com/appsync/latest/devguide/test-resolvers.html)
+ [從 VTL 遷移到 JavaScript](https://docs.aws.amazon.com/appsync/latest/devguide/migrating-resolvers.html)
+ [在直接資料來源存取和透過 Lambda 資料來源代理之間進行選擇](https://docs.aws.amazon.com/appsync/latest/devguide/choosing-data-source.html)