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

# 入門：在 AWS AppSync 中建立您的第一個 GraphQL API
<a name="quickstart"></a>

您可以使用 AWS AppSync 主控台來設定和啟動 GraphQL API。GraphQL APIs通常需要三個元件：

1. **GraphQL 結構描述** - 您的 GraphQL 結構描述是 API 的藍圖。它定義了您可以在執行 操作時請求的類型和欄位。若要將資料填入結構描述，您必須將資料來源連線至 GraphQL API。在本快速入門指南中，我們將使用預先定義的模型建立結構描述。

1. **資料來源** - 這些資源包含用於填入 GraphQL API 的資料。這可以是 DynamoDB 資料表、Lambda 函數等。 AWS AppSync 支援多種資料來源，以建置強大且可擴展的 GraphQL APIs。資料來源會連結到結構描述中的欄位。每當在 欄位上執行請求時，來源的資料就會填入 欄位。此機制由解析程式控制。在本快速入門指南中，我們將使用預先定義的模型以及結構描述來建立資料來源。

1. **解析程式** - 解析程式負責將結構描述欄位連結至資料來源。它們從來源擷取資料，然後根據 欄位定義的內容傳回結果。 AWS AppSync 支援 JavaScript 和 VTL，以寫入 GraphQL APIs 的解析程式。在本快速入門指南中，將根據結構描述和資料來源自動產生解析程式。在本節中，我們不會深入探討這一點。

AWS AppSync 支援建立和設定所有 GraphQL 元件。開啟 主控台時，您可以使用下列方法來建立 API：

1. 透過預先定義的模型產生自訂 GraphQL API，並設定新的 DynamoDB 資料表 （資料來源） 以支援它。

1. 設計具有空白結構描述且沒有資料來源或解析程式的 GraphQL API。

1. 使用 DynamoDB 資料表匯入資料並產生結構描述的類型和欄位。

1. 使用 AWS AppSync 的 WebSocket 功能和 Pub/Sub 架構來開發即時 APIs。

1. 使用現有的 GraphQL APIs （來源 APIs) 連結至合併 API。

**注意**  
建議您先檢閱[設計結構描述區段，](designing-your-schema.md#aws-appsync-designing-your-schema)再使用更進階的工具。這些指南將說明更簡單的範例，您可以用概念方式在 AWS AppSync 中建置更複雜的應用程式。

AWS AppSync 也支援數個非主控台選項來建立 GraphQL APIs。其中包含：

1. AWS Amplify

1. AWS SAM

1. CloudFormation

1. CDK

 下列範例將示範如何使用預先定義的模型和 DynamoDB 建立 GraphQL API 的基本元件。

**Topics**
+ [啟動結構描述](schema-launch-start.md)
+ [導覽 AWS AppSync 主控台](console-tour.md)
+ [使用 GraphQL 變動將資料新增至 DynamoDB 資料表](add-data-with-graphql-mutation.md)
+ [使用 GraphQL 查詢從 DynamoDB 資料表擷取資料](retrieve-data-with-graphql-query.md)
+ [補充區段](next-steps.md)

# 在 AWS AppSync 主控台中啟動結構描述
<a name="schema-launch-start"></a>

在此範例中，您將建立 `Todo` API，允許使用者建立每日家務提醒`Todo`的項目，例如*完成任務*或*挑選雜貨*。此 API 將示範如何使用 GraphQL 操作，其中狀態會保留在 DynamoDB 資料表中。

實際上，建立第一個 GraphQL API 有三個主要步驟。您必須定義結構描述 （類型和欄位）、將資料來源連接至 欄位 （然後），然後寫入處理商業邏輯的解析程式。不過，主控台體驗會變更此項目的順序。我們將從定義資料來源與結構描述互動的方式開始，稍後再定義結構描述和解析程式。

**建立 GraphQL API**

1. 登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。

1. 在**儀表板**上，選擇 **Create API (建立 API)**。

1. 選取 **GraphQL APIs**時，選擇**從頭開始設計**。然後選擇**下一步**。

1. 針對 **API 名稱**，將預先填入的名稱變更為 **Todo API**，然後選擇**下一步**。
**注意**  
這裡也有其他選項，但我們在此範例中不會使用這些選項。

1. 在**指定 GraphQL 資源**區段中，執行下列動作：

   1. 選擇 **DynamoDB 資料表支援的建立類型**。
**注意**  
這表示我們將建立新的 DynamoDB 資料表，以做為資料來源連接。

   1. 在**模型名稱**欄位中，輸入 **Todo**。
**注意**  
我們的第一個需求是定義我們的結構描述。此**模型名稱**將是類型名稱，因此您實際執行的操作是建立`Todo`將存在於結構描述中的`type`稱為 ：  

      ```
      type Todo {}
      ```

   1. 在**欄位**下，執行下列動作：

      1. 建立名為 的欄位**id**，類型為 `ID`，必要設定為 `Yes`。
**注意**  
這些是將存在於您`Todo`類型範圍內的欄位。系統會呼叫您這裡的欄位名稱`id`，類型為 `ID!`：  

         ```
         type Todo {
         	id: ID!
         }
         ```
AWS AppSync 支援不同使用案例的多個純量值。

      1. 使用**新增欄位**，建立四個額外的欄位，並將`Name`值設定為 **name**、**when**、 **where**和 **description**。其`Type`值將是 `String`，而 `Array`和 `Required`值都會設定為 `No`。其會如下所示：  
![\[Model information form showing fields for a Todo model with ID, name, when, where, and description.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/model-information-tutorial.png)
**注意**  
完整類型及其欄位如下所示：  

         ```
         type Todo {
         	id: ID!
         	name: String
         	when: String
         	where: String
         	description: String
         }
         ```
由於我們使用這個預先定義的模型建立結構描述，因此它也會根據 `create`、 `delete`和 等類型填入數個樣板變動`update`，以協助您輕鬆填入資料來源。

   1. 在**設定模型資料表**下，輸入資料表名稱，例如 **TodoAPITable**。將**主索引鍵**設定為 `id`。
**注意**  
我們基本上正在建立一個名為 *TodoAPITable* 的新 DynamoDB 資料表，該資料表將連接到 API 作為我們的主要資料來源。我們的主索引鍵設定為我們在此之前定義的必要`id`欄位。請注意，這個新資料表是空白的，除了分割區索引鍵之外，不包含任何內容。

   1. 選擇**下一步**。

1. 檢閱您的變更，然後選擇**建立 API**。等待片刻，讓 AWS AppSync 服務完成建立您的 API。

您已成功建立 GraphQL API 及其結構描述和 DynamoDB 資料來源。為了總結上述步驟，我們選擇建立全新的 GraphQL API。我們定義了 API 的名稱，然後新增第一個類型的結構描述定義。我們定義了類型及其欄位，然後選擇透過建立新的 DynamoDB 資料表來將資料來源連接到其中一個欄位，其中沒有資料。

# 導覽 AWS AppSync 主控台
<a name="console-tour"></a>

在將資料新增至 DynamoDB 資料表之前，我們應該檢閱 AWS AppSync 主控台體驗的基本功能。頁面左側的 AWS AppSync 主控台標籤可讓使用者輕鬆導覽至 AWS AppSync 提供的任何主要元件或組態選項：

![\[AWS AppSync console navigation menu showing APIs, Todo API options, and Documentation link.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/explorer-example-5.jpg)


## 結構描述設計工具
<a name="schema-designer"></a>

選擇**結構描述**以檢視您剛建立的結構描述。如果您檢閱結構描述的內容，您會注意到它已載入大量協助程式操作，以簡化開發程序。在**結構描述**編輯器中，如果您捲動程式碼，最終將到達您在上一節中定義的模型：

```
type Todo {
	id: ID!
	name: String
	when: String
	where: String
	description: String
}
```

您的模型會成為在整個結構描述中使用的基本類型。我們將使用從此類型自動產生的變動，開始將資料新增至資料來源。

以下是有關**結構描述**編輯器的一些其他提示和事實：

1. 程式碼編輯器具有固定和錯誤檢查功能，您可以在撰寫自己的應用程式時使用。

1. 主控台右側顯示則會顯示已建立的 GraphQL 類型，以及不同最上層類型 (例如查詢) 的解析程式。

1. 將新類型新增至結構描述時 （例如 `type User {...}`)，您可以擁有 AWS AppSync 佈建 DynamoDB 資源。這些包括最符合您 GraphQL 資料存取模式的適當主索引鍵、排序索引鍵和索引設計。如果您選擇最上方的 **Create Resources (建立資源)**，並從選單選取其中一個使用者定義的類型，您便可以在結構描述設計中選擇不同的欄位選項。我們將在[設計結構描述](designing-your-schema.md#aws-appsync-designing-your-schema)區段中說明這一點。

### 解析程式組態
<a name="resolver-menu"></a>

在結構描述設計工具中，**解析程式**區段包含結構描述中的所有類型和欄位。如果您捲動欄位清單，您會注意到可以透過選擇連接將解析程式連接到特定欄位****。這將開啟程式碼編輯器，您可以在其中撰寫解析程式程式碼。 AWS AppSync 支援 VTL 和 JavaScript 執行期，您可以在頁面頂端選擇**動作**，然後選擇**更新執行期**來變更。在頁面底部，您也可以建立將依序執行數個操作的函數。不過，解析程式是進階主題，我們不會在本節中涵蓋該主題。

## 資料來源
<a name="data-sources-designer"></a>

選擇**資料來源**以檢視您的 DynamoDB 資料表。透過選擇 `Resource`選項 （如果可用），您可以檢視資料來源的組態。在我們的範例中，這會導致 DynamoDB 主控台。您可以從那裡編輯資料。您也可以選擇資料來源，然後選擇編輯，直接**編輯**部分資料。如果您需要刪除資料來源，您可以選擇資料來源，然後選取**刪除**。最後，您可以選擇建立資料來源，然後設定名稱和類型，以建立新的**資料來源**。請注意，此選項用於將 AWS AppSync 服務連結至現有資源。您仍然需要使用相關服務在帳戶中建立資源， AWS AppSync 才會辨識該資源。

## 查詢
<a name="queries-editor"></a>

選擇**查詢**以檢視您的查詢和變動。當我們使用模型建立 GraphQL API 時， AWS AppSync 會自動產生一些協助程式變動和查詢，以供測試之用。在查詢編輯器中，左側包含 **Explorer**。這是顯示所有變動和查詢的清單。您可以按一下操作和欄位的名稱值，輕鬆啟用您想要在這裡使用的操作和欄位。這會導致程式碼自動出現在編輯器的中央部分。在這裡，您可以透過修改值來編輯您的變動和查詢。在編輯器底部，您有**查詢變數**編輯器，可讓您輸入操作輸入變數的欄位值。在編輯器頂端選擇**執行**將出現下拉式清單，以選取要執行的查詢/變動。此執行的輸出會出現在頁面右側。回到頂端的 **Explorer** 區段，您可以選擇 操作 （查詢、變動、訂閱），然後選擇 **\$1** 符號來新增該特定操作的新執行個體。在頁面頂端，將會有另一個下拉式清單，其中包含查詢執行的授權模式。不過，我們不會涵蓋本節中的該功能 （如需詳細資訊，請參閱[安全性](security-authz.md#aws-appsync-security)。)。

## 設定
<a name="console-settings"></a>

選擇**設定**以檢視 GraphQL API 的一些組態選項。在這裡，您可以啟用一些選項，例如記錄、追蹤和 Web 應用程式防火牆功能。您也可以新增新的授權模式，以保護資料免受不必要的公開洩漏。不過，這些選項更為進階，不會在本節中涵蓋。

**注意**  
預設授權模式 `API_KEY`使用 API 金鑰來測試應用程式。這是授予所有新建立的 GraphQL APIs 的基本授權。建議您使用不同的生產方法。為了本節中的範例，我們只會使用 API 金鑰。如需支援的授權方法的詳細資訊，請參閱[安全性](security-authz.md#aws-appsync-security)。

# 使用 GraphQL 變動將資料新增至 AWS AppSync 主控台中的 DynamoDB 資料表
<a name="add-data-with-graphql-mutation"></a>

您的下一個步驟是使用 GraphQL 變動將資料新增至空白 DynamoDB 資料表。變動是 GraphQL 中的基本操作類型之一。它們在結構描述中定義，可讓您操作資料來源中的資料。在 REST APIs方面，這些與 `PUT`或 等操作非常相似`POST`。

**將資料新增至資料來源**

1. 如果您尚未這麼做，請登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。

1. 從資料表中選擇您的 API。

1. 在左側的索引標籤中，選擇**查詢**。

1. 在資料表左側的 **Explorer** 索引標籤中，您可能會看到已在查詢編輯器中定義的數個變動和查詢：  
![\[Explorer tab showing a dropdown menu with mutation and query options like createTodo and deleteTodo.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/explorer-example-1.png)
**注意**  
此變動實際上位於您的結構描述中做為 `Mutation`類型。它具有程式碼：  

   ```
   type Mutation {
   	createTodo(input: CreateTodoInput!): Todo
   	updateTodo(input: UpdateTodoInput!): Todo
   	deleteTodo(input: DeleteTodoInput!): Todo
   }
   ```
如您所見，這裡的操作與查詢編輯器中的操作類似。

   AWS AppSync 會自動從我們先前定義的模型產生這些項目。此範例將使用 `createTodo` 變動將項目新增至我們的 *TodoAPITable* 資料表。

1. 在`createTodo`變動下展開操作，以選擇`createTodo`操作：  
![\[Expanded createTodo mutation showing input fields like description, id, name, when, and where.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/explorer-example-2.png)

   啟用上圖等所有欄位的核取方塊。
**注意**  
您在這裡看到的屬性是變動的不同可修改元素。`input` 您可以將 視為 的 參數`createTodo`。具有核取方塊的各種選項是執行 操作後，將在回應中傳回的欄位。

1. 在畫面中央的程式碼編輯器中，您會注意到 操作會出現在`createTodo`變動下方：

   ```
   mutation createTodo($createtodoinput: CreateTodoInput!) {
     createTodo(input: $createtodoinput) {
       where
       when
       name
       id
       description
     }
   }
   ```
**注意**  
為了正確解釋此程式碼片段，我們也必須查看結構描述程式碼。宣告`mutation createTodo($createtodoinput: CreateTodoInput!){}`是具有其中一個操作 的變動`createTodo`。完整變動位於結構描述中：  

   ```
   type Mutation {
   	createTodo(input: CreateTodoInput!): Todo
   	updateTodo(input: UpdateTodoInput!): Todo
   	deleteTodo(input: DeleteTodoInput!): Todo
   }
   ```
從編輯器返回變動宣告， 參數是名為 `$createtodoinput` 且必要輸入類型為 的物件`CreateTodoInput`。請注意， `CreateTodoInput`（以及變動中的所有輸入） 也會在結構描述中定義。例如，以下是 的樣板程式碼`CreateTodoInput`：  

   ```
   input CreateTodoInput {
   	name: String
   	when: String
   	where: String
   	description: String
   }
   ```
它包含我們在模型中定義的欄位，即 `name`、`where`、 `when`和 `description`。  
返回編輯器程式碼，在 中`createTodo(input: $createtodoinput) {}`，我們將輸入宣告為 `$createtodoinput`，該輸入也用於變動宣告。我們這樣做是因為這允許 GraphQL 根據提供的類型驗證我們的輸入，並確保它們與正確的輸入一起使用。  
編輯器程式碼的最後一部分顯示執行 操作後，將在回應中傳回的欄位：  

   ```
   {
       where
       when
       name
       id
       description
     }
   ```

   在此編輯器下方的**查詢變數**索引標籤中，會有一般`createtodoinput`物件可能具有下列資料：

   ```
   {
     "createtodoinput": {
       "name": "Hello, world!",
       "when": "Hello, world!",
       "where": "Hello, world!",
       "description": "Hello, world!"
     }
   }
   ```
**注意**  
這是我們為先前提到的輸入配置值的位置：  

   ```
   input CreateTodoInput {
   	name: String
   	when: String
   	where: String
   	description: String
   }
   ```

   透過新增要在 DynamoDB 資料表中放置的資訊`createtodoinput`來變更 。在這種情況下，我們希望建立一些`Todo`項目作為提醒：

   ```
   {
     "createtodoinput": {
       "name": "Shopping List",
       "when": "Friday",
       "where": "Home",
       "description": "I need to buy eggs"
     }
   }
   ```

1. 選擇編輯器頂端的**執行**。在下拉式清單中選擇 **createTodo**。在編輯器的右側，您應該會看到回應。這可能看起來如下：

   ```
   {
     "data": {
       "createTodo": {
         "where": "Home",
         "when": "Friday",
         "name": "Shopping List",
         "id": "abcdefgh-1234-1234-1234-abcdefghijkl",
         "description": "I need to buy eggs"
       }
     }
   }
   ```

   如果您導覽至 DynamoDB 服務，您現在會在資料來源中看到包含此資訊的項目：  
![\[TodoAPITable interface showing a completed scan with 1 item returned in a table format.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/explorer-example-3.png)

為了摘要說明操作，GraphQL 引擎會剖析記錄，而解析程式會將記錄插入您的 Amazon DynamoDB 資料表。同樣地，您可以在 DynamoDB 主控台中驗證此項目。請注意，您不需要傳入 `id`值。在結果中`id`產生並傳回 。這是因為範例針對 DynamoDB 資源上設定的分割區索引鍵，在 GraphQL 解析程式中使用 `autoId()`函數。我們將介紹如何在不同的區段中建置解析程式。請記下傳回`id`的值；您將在下一節中使用它來擷取具有 GraphQL 查詢的資料。

# 使用 GraphQL 查詢從 AWS AppSync 主控台中的 DynamoDB 資料表擷取資料
<a name="retrieve-data-with-graphql-query"></a>

現在您的資料庫中存在記錄，您會在執行查詢時取得結果。查詢是 GraphQL 的其他基本操作之一。它用於從資料來源剖析和擷取資訊。在 REST APIs方面，這類似於 `GET`操作。GraphQL 查詢的主要優點是能夠指定應用程式的確切資料需求，以便您適時擷取相關資料。

**查詢資料來源**

1. 如果您尚未這麼做，請登入 AWS 管理主控台 並開啟 [AppSync 主控台](https://console.aws.amazon.com/appsync/)。

1. 從資料表中選擇您的 API。

1. 在左側的索引標籤中，選擇**查詢**。

1. 在資料表左側的 **Explorer** 索引標籤中，於 `query` 下方`listTodos`展開`getTodo`操作：  
![\[Expanded getTodo operation showing fields id, description, name, when, and where.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/explorer-example-4.png)

1. 在程式碼編輯器中，您應該會看到操作程式碼：

   ```
   query listTodos {
     getTodo(id: "") {
       description
       id
       name
       when
       where
     }
   ```

   在 中`(id:"")`，填入您在變動操作結果中儲存的值。在我們的範例中，這將是：

   ```
   query listTodos {
     getTodo(id: "abcdefgh-1234-1234-1234-abcdefghijkl") {
       description
       id
       name
       when
       where
     }
   ```

1. 選擇**執行**，然後選擇 **listTodos**。結果會顯示在編輯器的右側。我們的範例如下所示：

   ```
   {
     "data": {
       "getTodo": {
         "description": "I need to buy eggs",
         "id": "abcdefgh-1234-1234-1234-abcdefghijkl",
         "name": "Shopping List",
         "when": "Friday",
         "where": "Home"
       }
     }
   }
   ```
**注意**  
查詢只會傳回您指定的欄位。您可以從傳回欄位刪除不需要的欄位，取消選取這些欄位：  

   ```
   {
       description
       id
       name
       when
       where
     }
   ```
您也可以取消勾選您要刪除之欄位旁的 **Explorer** 索引標籤中的方塊。

1. 您也可以重複在資料來源中建立項目的步驟，然後使用 `listTodos`操作重複查詢步驟，以嘗試`listTodos`操作。以下是我們新增第二個任務的範例：

   ```
   {
     "createtodoinput": {
       "name": "Second Task",
       "when": "Monday",
       "where": "Home",
       "description": "I need to mow the lawn"
     }
   }
   ```

   透過呼叫 `listTodos`操作，它會傳回舊項目和新項目：

   ```
   {
     "data": {
       "listTodos": {
         "items": [
           {
             "id": "abcdefgh-1234-1234-1234-abcdefghijkl",
             "name": "Shopping List",
             "when": "Friday",
             "where": "Home",
             "description": "I need to buy eggs"
           },
           {
             "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
             "name": "Second Task",
             "when": "Monday",
             "where": "Home",
             "description": "I need to mow the lawn"
           }
         ]
       }
     }
   }
   ```

# 適用於 AWS AppSync 主控台的補充區段
<a name="next-steps"></a>

這些區段是更進階 AWS AppSync 主題的參考。建議您先遵循*補充讀取*區段，再執行任何其他動作。

## 整合
<a name="app-integration"></a>

在主控台索引標籤中，如果您選擇 API 的名稱，則會顯示**整合**頁面：

![\[AWS AppSync sidebar menu with APIs, Todo API highlighted, and other options listed.\]](http://docs.aws.amazon.com/zh_tw/appsync/latest/devguide/images/explorer-example-6.png)


它總結了設定 API 的步驟，並概述了建置用戶端應用程式的後續步驟。**與您的應用程式整合**區段提供使用 [AWS Amplify 工具鏈](https://aws-amplify.github.io/)的詳細資訊，透過組態和程式碼產生來自動化將 API 與 iOS、Android 和 JavaScript 應用程式連線的程序。Amplify 工具鏈提供從本機工作站建置專案的完整支援，包括 GraphQL 佈建和 CI/CD 的工作流程。

**用戶端範例**區段也會列出用於測試end-to-end體驗的範例用戶端應用程式 （例如 JavaScript、iOS、Android)。您可以複製和下載這些範例，而且組態檔案具有開始使用所需的必要資訊 （例如您的端點 URL)。遵循[AWS Amplify 工具鏈](https://aws-amplify.github.io/)頁面上的指示來執行您的應用程式。

## 補充讀取
<a name="supplemental-reading-quickstart"></a>
+ [使用 設計 GraphQL APIs AWS AppSync](designing-a-graphql-api.md) - 這是使用不含資料來源或解析程式的空白結構描述建立 GraphQL 的完整指南。