建構 GraphQL 結構描述建立結構描述將類型新增至結構描述選用考量 - 使用列舉做為狀態選用考量 - 訂閱選用考量 - 關係和分頁

設計 GraphQL 結構描述

GraphQL 結構描述是任何 GraphQL 伺服器實作的基礎。每個 GraphQL API由單一結構描述定義，其中包含描述請求資料如何填入的類型和欄位。流經 API和執行操作的資料必須針對結構描述進行驗證。

一般而言，GraphQL 類型系統會描述 GraphQL 伺服器的功能，並用來判斷查詢是否有效。伺服器類型系統通常稱為該伺服器的結構描述，並且可以包含不同的物件類型、純量類型、輸入類型等。GraphQL 既是宣告性，也是強烈輸入，這意味著在執行階段時，類型會定義良好，並且只會傳回指定的類型。

AWS AppSync 可讓您定義和設定 GraphQL 結構描述。下一節說明如何使用 AWS AppSync的服務從頭建立 GraphQL 結構描述。

建構 GraphQL 結構描述

提示

建議您先檢閱結構描述區段再繼續。

GraphQL 是實作 API服務的強大工具。根據 GraphQL 的網站，GraphQL 如下：

「GraphQL 是一種查詢語言，APIs也是使用現有資料完成這些查詢的執行期。GraphQL 提供中資料的完整且易於理解的說明API，讓客戶能夠確切地詢問他們需要什麼，什麼都不做，讓APIs隨著時間的推移更輕鬆發展，並啟用強大的開發人員工具。"

本節涵蓋 GraphQL 實作的第一部分：結構描述。使用上述引號，結構描述扮演「提供「中資料的完整且易於理解的描述API」的角色。換句話說，GraphQL 結構描述是服務的資料、操作及其之間的關係的文字表示。結構描述會被視為 GraphQL 服務實作的主要進入點。令人意外的是，這通常是您在專案中所做的第一件事之一。建議您先檢閱結構描述區段再繼續。

若要引述結構描述區段，GraphQL 結構描述會以結構描述定義語言 （）撰寫SDL。SDL 由具有已建立結構的類型和欄位組成：

類型：類型是 GraphQL 如何定義資料的形狀和行為。GraphQL 支援許多類型，本節稍後將說明這些類型。結構描述中定義的每種類型都會包含自己的範圍。在範圍內，一個或多個欄位可以包含 GraphQL 服務中使用的值或邏輯。類型會填滿許多不同的角色，最常見的是物件或純量（原始值類型）。
欄位：欄位存在於類型的範圍內，並保留從 GraphQL 服務請求的值。這些與其他程式設計語言的變數非常相似。您在欄位中定義的資料形狀將決定資料在請求/回應操作中的結構。這可讓開發人員在不了解服務的後端如何實作的情況下預測要傳回的內容。

最簡單的結構描述將包含三種不同的資料類別：

結構描述根目錄：根目錄定義結構描述的進入點。它指向將對資料執行一些操作的欄位，例如新增、刪除或修改某些內容。
類型：這些是基本類型，用於表示資料的形狀。您幾乎可以將這些視為具有定義特徵之物件或物件的摘要表示法。例如，您可以建立在資料庫中代表某個人的Person物件。每個人的特徵都會Person在中定義為欄位。它們可以是個人的名稱、年齡、工作、地址等。
特殊物件類型 ：這些是定義結構描述中操作行為的類型。每個特殊物件類型在每個結構描述中定義一次。它們首先放置在結構描述根中，然後在結構描述內文中定義。特殊物件類型中的每個欄位都會定義您的解析器要實作的單一操作。

若要將這一點納入考量，請想像您正在建立儲存作者和他們所撰寫書籍的服務。每個作者都有一個名稱和他們撰寫的書籍陣列。每本書都有一個名稱和相關聯的作者清單。我們也希望能夠新增或擷取書籍和作者。此關係的簡單UML表示方式可能如下所示：

UML diagram showing Author and Book classes with attributes and methods, linked by association.

在 GraphQL 中，實體Author和 Book表示結構描述中的兩種不同的物件類型：


type Author {
}

type Book {
}

Author 包含 authorName和 Books，而 Book包含 bookName和 Authors。這些可以表示為您類型範圍內的欄位：


type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

如您所見，類型表示式非常接近圖表。不過，這些方法會變得較棘手。這些將作為欄位放置在幾個特殊物件類型之一。他們的特殊物件分類取決於其行為。GraphQL 包含三種基本的特殊物件類型：查詢、突變和訂閱。如需詳細資訊，請參閱特殊物件。

由於 getAuthor和 getBook 都正在請求資料，因此它們將放置在Query特殊物件類型中：


type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

操作會連結至查詢，而查詢本身會連結至結構描述。新增結構描述根將定義特殊物件類型（Query 在此情況下）作為其中一個進入點。這可以使用schema關鍵字來完成：


schema {
  query: Query
}

type Author {
  authorName: String
  Books: [Book]
}

type Book {
  bookName: String
  Authors: [Author]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

檢視最後兩種方法，addAuthor並將資料addBook新增至您的資料庫，以便以Mutation特殊物件類型定義這些資料。但是，從類型頁面，我們也知道不允許直接參考物件的輸入，因為它們是嚴格輸出類型。在此情況下，我們無法使用 Author或 Book，因此我們需要使用相同的欄位建立輸入類型。在此範例中，我們新增了 AuthorInput和 BookInput，兩者都接受各自類型的相同欄位。然後，我們使用輸入作為參數來建立突變：


schema {
  query: Query
  mutation: Mutation
}

type Author {
  authorName: String
  Books: [Book]
}

input AuthorInput {
  authorName: String
  Books: [BookInput]
}

type Book {
  bookName: String
  Authors: [Author]
}

input BookInput {
  bookName: String
  Authors: [AuthorInput]
}

type Query {
  getAuthor(authorName: String): Author
  getBook(bookName: String): Book
}

type Mutation {
  addAuthor(input: [BookInput]): Author
  addBook(input: [AuthorInput]): Book
}

我們來回顧一下我們剛做過的事：

我們建立了一個包含 Book和 Author類型的結構描述，以代表我們的實體。
我們新增了包含我們實體特性的欄位。
我們已新增查詢，以便從資料庫擷取此資訊。
我們新增了突變來操作資料庫中的資料。
我們新增了輸入類型來取代突變中的物件參數，以符合 GraphQL 的規則。
我們已將查詢和突變新增至根結構描述，以便 GraphQL 實作了解根類型位置。

如您所見，建立結構描述的程序通常需要從資料建模（特別是資料庫建模）中取得許多概念。您可以將結構描述視為符合來源資料的形狀。它也可以作為解析程式將實作的模型。在以下各節中，您將了解如何使用各種 AWS後端工具和服務建立結構描述。

注意

下列各節中的範例並非要在真正的應用程式中執行。它們只用來展示命令，以便您可以建置自己的應用程式。

建立結構描述

您的結構描述將位於名為的檔案中schema.graphql。 AWS AppSync 允許使用者APIs使用各種方法為其 GraphQL 建立新的結構描述。在此範例中，我們將建立空白API和空白結構描述。

Console

登入 AWS Management Console 並開啟AppSync主控台。
1. 在儀表板 中，選擇建立 API。
2. 在API選項 下，選擇 GraphQL APIs、從頭開始設計 ，然後選擇下一步 。
  1. 對於API名稱 ，請將預先填入的名稱變更為應用程式所需的名稱。
  2. 如需聯絡詳細資訊 ，您可以輸入聯絡點，以識別的管理員API。此為選用欄位。
  3. 在私有API組態 下，您可以啟用私有API功能。私有API只能從設定的VPC端點存取（VPCE）。如需詳細資訊，請參閱私有 APIs。
    
    我們不建議在此範例中啟用此功能。檢閱您的輸入後，請選擇下一步。
3. 在建立 GraphQL 類型 下，您可以選擇建立 DynamoDB 資料表以用作資料來源，或略過此項目，稍後再執行此動作。
  
  在此範例中，選擇稍後建立 GraphQL 資源。我們將在單獨的區段中建立資源。
4. 檢閱您的輸入，然後選擇建立 API。
您將位於特定的儀表板中API。您可以指出 API的名稱會位於儀表板頂端。如果不是這種情況，您可以在 Sidebar APIs中選擇，然後在儀表板 API中選擇您的。 APIs
1. 在 API名稱下方的 Sidebar 中，選擇結構描述 。
在結構描述編輯器 中，您可以設定schema.graphql檔案。它可以是空的，或填滿從模型產生的類型。在右側，您有解析程式區段，用於將解析程式連接至結構描述欄位。我們不會在本節中查看解析程式。

CLI

注意

使用時CLI，請確定您擁有存取和建立服務資源的正確許可。您可能想要為需要存取服務的非管理員使用者設定最低權限政策。如需 AWS AppSync 政策的詳細資訊，請參閱的身分和存取管理 AWS AppSync。

此外，如果您尚未閱讀主控台版本，建議您先閱讀該版本。

如果您尚未這麼做，請 AWS 安裝 CLI，然後新增您的組態。

執行 create-graphql-api命令來建立 GraphQL API 物件。

您需要為此特定命令輸入兩個參數：

您 name的 API。
authentication-type、或用於存取 API（IAM、 OIDC等）的憑證類型。

注意

必須Region設定其他參數，但通常會預設為您的CLI組態值。

範例命令可能如下所示：


aws appsync create-graphql-api --name testAPI123 --authentication-type API_KEY

輸出會在中傳回CLI。範例如下：


{
    "graphqlApi": {
        "xrayEnabled": false,
        "name": "testAPI123",
        "authenticationType": "API_KEY",
        "tags": {},
        "apiId": "abcdefghijklmnopqrstuvwxyz",
        "uris": {
            "GRAPHQL": "https://zyxwvutsrqponmlkjihgfedcba.appsync-api.us-west-2.amazonaws.com/graphql",
            "REALTIME": "wss://zyxwvutsrqponmlkjihgfedcba.appsync-realtime-api.us-west-2.amazonaws.com/graphql"
        },
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz"
    }
}

注意
這是選用的命令，會擷取現有的結構描述，並使用 base-64 blob 將其上傳至 AWS AppSync 服務。我們不會為了此範例而使用此命令。

執行 start-schema-creation 命令。

您需要為此特定命令輸入兩個參數：
1. 上一個步驟api-id中的。
2. 結構描述definition是 base-64 編碼的二進位 Blob。
範例命令可能如下所示：
```
 aws appsync start-schema-creation --api-id abcdefghijklmnopqrstuvwxyz --definition "aa1111aa-123b-2bb2-c321-12hgg76cc33v"
```
將傳回輸出：
```
{
    "status": "PROCESSING"
}
```
此命令不會在處理後傳回最終輸出。您必須使用單獨的命令 get-schema-creation-status，才能查看結果。請注意，這兩個命令是非同步的，因此即使仍在建立結構描述，您也可以檢查輸出狀態。

CDK

提示

在使用之前CDK，建議您檢閱 CDK的正式文件以及 AWS AppSync的CDK參考。

下列步驟只會顯示用來新增特定資源的程式碼片段的一般範例。這並非生產程式碼中的有效解決方案。我們也假設您已經有運作中的應用程式。

的起點略CDK有不同。理想情況下，應該已建立您的schema.graphql檔案。您只需要使用副檔名建立新的.graphql檔案。這可以是空檔案。
一般而言，您可能需要將匯入指令新增至您正在使用的服務。例如，它可以遵循以下表單：
```
import * as x from 'x'; # import wildcard as the 'x' keyword from 'x-service'
import {a, b, ...} from 'c'; # import {specific constructs} from 'c-service'
```
若要新增 GraphQL API，您的堆疊檔案需要匯入 AWS AppSync 服務：
```
import * as appsync from 'aws-cdk-lib/aws-appsync';
```
注意
這表示我們正在appsync關鍵字下匯入整個服務。若要在應用程式中使用此功能，您的 AWS AppSync 建構會使用格式 appsync.construct_name。例如，如果我們想要製作 GraphQL API，我們會說 new appsync.GraphqlApi(args_go_here)。下列步驟描述了這一點。
最基本的 GraphQL API將包含name適用於 API和 schema 路徑的。
```
const add_api = new appsync.GraphqlApi(this, 'API_ID', {
  name: 'name_of_API_in_console',
  schema: appsync.SchemaFile.fromAsset(path.join(__dirname, 'schema_name.graphql')),
});
```
注意
我們來檢閱此程式碼片段的功能。在範圍內api，我們API透過呼叫建立新的 GraphQLappsync.GraphqlApi(scope: Construct, id: string, props: GraphqlApiProps)。範圍為 this，其代表目前的物件。ID 為 API_ID，這將在建立 GraphQL AWS CloudFormation 時作為中的API資源名稱。GraphqlApiProps 包含 GraphQL API和 name的 schema。schema 將搜尋.graphql檔案（SchemaFile.fromAsset）的絕對路徑（）來產生結構描述（__dirname）schema_name.graphql）。在實際情況下，您的結構描述檔案可能位於CDK應用程式內。
若要使用對 GraphQL 所做的變更API，您必須重新部署應用程式。

將類型新增至結構描述

現在您已新增結構描述，您可以開始同時新增輸入和輸出類型。請注意，此處的類型不應用於真實程式碼；它們只是協助您了解程序的範例。

首先，我們將建立物件類型。在真實程式碼中，您不需要從這些類型開始。只要遵循 GraphQL 的規則和語法，您隨時都可以製作任何想要的類型。

注意

接下來的幾個區段將使用結構描述編輯器 ，因此請保持開啟狀態。

Console

您可以使用 type關鍵字以及類型的名稱來建立物件類型：
```
type Type_Name_Goes_Here {}
```
在類型範圍內，您可以新增代表物件特徵的欄位：
```
type Type_Name_Goes_Here {
  # Add fields here
}
```
範例如下：
```
type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}
```
注意
在此步驟中，我們新增了一個一般物件類型，其中必要id欄位會儲存為 ID，title欄位會儲存為 String，而date欄位會儲存為 AWSDateTime。若要查看類型和欄位清單及其功能，請參閱結構描述。若要查看純量清單及其功能，請參閱類型參考。

CLI

注意

如果您尚未閱讀主控台版本，建議您先閱讀該版本。

您可以執行 create-type命令來建立物件類型。

您需要為此特定命令輸入幾個參數：
1. 您 api-id的 API。
2. definition或類型的內容。在主控台範例中，這是：
```
type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}
```
3. 您輸入的 format 。在此範例中，我們使用 SDL。
範例命令可能如下所示：
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Obj_Type_1{id: ID! title: String date: AWSDateTime}" --format SDL
```
輸出會在中傳回CLI。範例如下：
```
{
    "type": {
        "definition": "type Obj_Type_1{id: ID! title: String date: AWSDateTime}",
        "name": "Obj_Type_1",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Obj_Type_1",
        "format": "SDL"
    }
}
```
注意
在此步驟中，我們新增了一個一般物件類型，其中必要id欄位會儲存為 ID，title欄位會儲存為 String，而date欄位會儲存為 AWSDateTime。若要查看類型和欄位清單及其功能，請參閱結構描述。若要查看純量清單及其功能，請參閱類型參考。
進一步說明，您可能已意識到輸入定義直接適用於較小的類型，但無法新增較大的或多種類型。您可以選擇在.graphql檔案中新增所有內容，然後傳遞為輸入。

CDK

提示

在使用之前CDK，建議您檢閱 CDK的正式文件以及 AWS AppSync的CDK參考。

下列步驟只會顯示用來新增特定資源的程式碼片段的一般範例。這並非生產程式碼中的有效解決方案。我們也假設您已經有運作中的應用程式。

若要新增類型，您需要將其新增至您的.graphql檔案。例如，主控台範例為：


type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

您可以將類型直接新增至結構描述，就像任何其他檔案一樣。

注意

若要使用對 GraphQL 所做的變更API，您必須重新部署應用程式。

物件類型具有純量類型的欄位，例如字串和整數。 AWS AppSync 也可讓您使用增強純量類型，例如AWSDateTime基礎 GraphQL 純量。此外，結束於驚嘆號的任何欄位都是必要的。

特別是ID純量類型是唯一的識別符，可以是 String或 Int。您可以在解析器程式碼中控制這些項目以進行自動指派。

特殊物件類型之間存在相似之處，例如 Query和上述範例的「一般」物件類型，因為它們都使用type關鍵字，並被視為物件。不過，對於特殊物件類型（Query、和 Subscription）Mutation，其行為大不相同，因為它們會公開為的進入點API。他們也更關注的是塑造操作，而不是資料。如需詳細資訊，請參閱查詢和突變類型。

在特殊物件類型的主題上，下一個步驟可能是新增一或多個物件，以對形狀資料執行操作。在實際案例中，每個 GraphQL 結構描述至少都必須具有請求資料的根查詢類型。您可以將查詢視為 GraphQL 伺服器的其中一個進入點（或端點）。讓我們新增查詢做為範例。

Console

若要建立查詢，您只需將其新增至結構描述檔案，就像任何其他類型一樣。查詢需要Query類型和根中的項目，如下所示：
```
schema {
  query: Name_of_Query
}

type Name_of_Query {
  # Add field operation here
}
```
請注意 Name_of_Query 在生產環境中，Query在大多數情況下只會呼叫。我們建議將其保持在此值。在查詢類型中，您可以新增欄位。每個欄位都會在請求中執行操作。因此，如果不是全部，則大多數這些欄位都會連接至解析器。不過，我們在此區段中並不關心這一點。關於欄位操作的格式，其可能看起來像這樣：
```
Name_of_Query(params): Return_Type # version with params
Name_of_Query: Return_Type # version without params
```
範例如下：
```
schema {
  query: Query
}

type Query {
  getObj: [Obj_Type_1]
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}
```
注意
在此步驟中，我們新增了類型，並在schema根中定義了該Query類型。我們的Query類型定義了傳回Obj_Type_1物件清單getObj的欄位。請注意， Obj_Type_1是上一個步驟的物件。在生產程式碼中，您的欄位操作通常會使用這類物件所塑造的資料Obj_Type_1。此外，像這樣的欄位getObj通常具有執行業務邏輯的解析器。這將在不同的章節中介紹。
此外，會在匯出期間 AWS AppSync 自動新增結構描述根目錄，因此在技術上，您不需要將其直接新增至結構描述。我們的服務會自動處理重複的結構描述。我們會將它新增至此處作為最佳實務。

CLI

注意

如果您尚未閱讀主控台版本，建議您先閱讀該版本。

執行 create-type命令，以建立具有 query定義的schema根。

您需要為此特定命令輸入幾個參數：
1. 您 api-id的 API。
2. definition或類型的內容。在主控台範例中，這是：
```
schema {
  query: Query
}
```
3. 您輸入的 format 。在此範例中，我們使用 SDL。
範例命令可能如下所示：
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "schema {query: Query}" --format SDL
```
輸出會在中傳回CLI。範例如下：
```
{
    "type": {
        "definition": "schema {query: Query}",
        "name": "schema",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
        "format": "SDL"
    }
}
```
注意
請注意，如果您未在create-type命令中正確輸入內容，您可以執行命令來更新結構描述根目錄（或結構描述中的任何類型）update-type。在此範例中，我們將暫時變更結構描述根目錄，以包含subscription定義。
您需要為此特定命令輸入幾個參數：
1. 您 api-id的 API。
2. type-name 您類型的。在主控台範例中，這是 schema。
3. definition或類型的內容。在主控台範例中，這是：
  
  schema { query: Query }
  
  新增後的結構描述subscription如下所示：
  
  schema { query: Query subscription: Subscription }
4. 您輸入的 format 。在此範例中，我們使用 SDL。
範例命令可能如下所示：
```
aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query subscription: Subscription}" --format SDL
```
輸出會在中傳回CLI。範例如下：
```
{
    "type": {
        "definition": "schema {query: Query subscription: Subscription}",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
        "format": "SDL"
    }
}
```
新增預先格式化的檔案仍然可以在此範例中運作。
執行 create-type命令來建立Query類型。

您需要為此特定命令輸入幾個參數：
1. 您 api-id的 API。
2. definition或類型的內容。在主控台範例中，這是：
```
type Query {
  getObj: [Obj_Type_1]
}
```
3. 您輸入的 format 。在此範例中，我們使用 SDL。
範例命令可能如下所示：
```
aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Query {getObj: [Obj_Type_1]}" --format SDL
```
輸出會在中傳回CLI。範例如下：
```
{
    "type": {
        "definition": "Query {getObj: [Obj_Type_1]}",
        "name": "Query",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Query",
        "format": "SDL"
    }
}
```
注意
在此步驟中，我們新增了類型，並在您的schema根中定義了該Query類型。我們的Query類型定義了傳回Obj_Type_1物件清單getObj的欄位。
在schema根碼中query: Query， query:部分表示已在結構描述中定義查詢，而 Query部分表示實際的特殊物件名稱。

CDK

提示

在使用之前CDK，建議您檢閱 CDK的正式文件以及 AWS AppSync的CDK參考。

下列步驟只會顯示用來新增特定資源的程式碼片段的一般範例。這並非生產程式碼中的有效解決方案。我們也假設您已經有運作中的應用程式。

您需要將查詢和結構描述根新增至 .graphql 檔案。我們的範例看起來像以下範例，但您會想要將其取代為實際的結構描述程式碼：


schema {
  query: Query
}

type Query {
  getObj: [Obj_Type_1]
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

您可以將類型直接新增至結構描述，就像任何其他檔案一樣。

注意

更新結構描述根是選用的。我們在此範例中新增了此範例做為最佳實務。

若要使用對 GraphQL 所做的變更API，您必須重新部署應用程式。

您現在已看到建立物件和特殊物件（查詢）的範例。您亦已了解如何互連這些項目來描述資料和操作。您可以擁有僅具有資料描述和一或多個查詢的結構描述。不過，我們希望新增另一個操作，將資料新增至資料來源。我們會新增另一個名為的特殊物件類型Mutation，以修改資料。

Console

突變將稱為 Mutation。如同 Query，內部的欄位操作Mutation會描述操作，並將連接至解析器。此外，請注意，我們需要在schema根中定義它，因為它是一種特殊的物件類型。以下是突變的範例：
```
schema {
  mutation: Name_of_Mutation
}

type Name_of_Mutation {
  # Add field operation here
}
```
典型的突變會如查詢般列在根中。突變是使用type關鍵字和名稱來定義。Name_of_Mutation 通常稱為 Mutation，因此建議您以這種方式保留它。每個欄位也會執行操作。關於欄位操作的格式，其可能看起來像這樣：
```
Name_of_Mutation(params): Return_Type # version with params
Name_of_Mutation: Return_Type # version without params
```
範例如下：
```
schema {
  query: Query
  mutation: Mutation
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

type Query {
  getObj: [Obj_Type_1]
}

type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}
```
注意
在此步驟中，我們新增了具有 addObj 欄位的Mutation類型。讓我們總結此欄位的功能：
```
addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
```
addObj 正在使用 Obj_Type_1 物件來執行操作。這是顯而易見的，因為欄位，但語法會在: Obj_Type_1傳回類型中證明這一點。在中addObj，它接受Obj_Type_1來自物件的 title、 id和 date 欄位作為參數。如您所見，它看起來很像方法宣告。但是，我們尚未描述方法的行為。如前所述，結構描述只會用來定義資料和操作的內容，而不是它們的運作方式。當我們建立第一個解析程式時，實作實際的業務邏輯稍後會開始。
完成結構描述後，您可以選擇將其匯出為 schema.graphql 檔案。在結構描述編輯器 中，您可以選擇匯出結構描述，以支援的格式下載檔案。
此外，會在匯出期間 AWS AppSync 自動新增結構描述根目錄，因此在技術上，您不需要將其直接新增至結構描述。我們的服務會自動處理重複的結構描述。我們會將它新增至此處作為最佳實務。

CLI

注意

如果您尚未閱讀主控台版本，建議您先閱讀該版本。

執行 update-type命令來更新根結構描述。

您需要為此特定命令輸入幾個參數：

您 api-id的 API。
type-name 您類型的。在主控台範例中，這是 schema。
definition或類型的內容。在主控台範例中，這是：
```
schema {
  query: Query
  mutation: Mutation
}
```
您輸入的 format 。在此範例中，我們使用 SDL。

範例命令可能如下所示：


aws appsync update-type --api-id abcdefghijklmnopqrstuvwxyz --type-name schema --definition "schema {query: Query mutation: Mutation}" --format SDL

輸出會在中傳回CLI。範例如下：


{
    "type": {
        "definition": "schema {query: Query mutation: Mutation}",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/schema",
        "format": "SDL"
    }
}

執行 create-type命令來建立Mutation類型。

您需要為此特定命令輸入幾個參數：

您 api-id的 API。

definition或類型的內容。在主控台範例中，這是


type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}

您輸入的 format 。在此範例中，我們使用 SDL。

範例命令可能如下所示：


aws appsync create-type --api-id abcdefghijklmnopqrstuvwxyz --definition "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}" --format SDL

輸出會在中傳回CLI。範例如下：


{
    "type": {
        "definition": "type Mutation {addObj(id: ID! title: String date: AWSDateTime): Obj_Type_1}",
        "name": "Mutation",
        "arn": "arn:aws:appsync:us-west-2:107289374856:apis/abcdefghijklmnopqrstuvwxyz/types/Mutation",
        "format": "SDL"
    }
}

CDK

提示

在使用之前CDK，建議您檢閱 CDK的正式文件以及 AWS AppSync的CDK參考。

下列步驟只會顯示用來新增特定資源的程式碼片段的一般範例。這並非生產程式碼中的有效解決方案。我們也假設您已經有運作中的應用程式。

您需要將查詢和結構描述根新增至 .graphql 檔案。我們的範例看起來像以下範例，但您會想要將其取代為實際的結構描述程式碼：


schema {
  query: Query
  mutation: Mutation
}

type Obj_Type_1 {
  id: ID!
  title: String
  date: AWSDateTime
}

type Query {
  getObj: [Obj_Type_1]
}

type Mutation {
  addObj(id: ID!, title: String, date: AWSDateTime): Obj_Type_1
}

注意

更新結構描述根是選用的。我們在此範例中新增了此範例做為最佳實務。

若要使用對 GraphQL 所做的變更API，您必須重新部署應用程式。

選用考量 - 使用列舉做為狀態

此時，您知道如何建立基本結構描述。不過，您可以新增許多項目來增加結構描述的功能。應用程式中找到的一件常見問題是使用列舉作為狀態。您可以使用列舉來強制在呼叫時選擇一組值中的特定值。這對您知道不會長時間發生劇烈變化的事物來說是有利的。假設說，我們可以新增一個 enum，傳回回應中的狀態碼或字串。

例如，假設我們製作的社交媒體應用程式正在後端中儲存使用者的貼文資料。我們的結構描述包含代表個別文章資料的Post類型：


type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

我們的 Post 將包含唯一 id、貼文 title date 、貼文，以及一個名為的列舉PostStatus，代表應用程式處理貼文時的狀態。對於我們的操作，我們將有一個查詢，會傳回所有貼文資料：


type Query {
  getPosts: [Post]
}

我們也會有一個突變，將文章新增至資料來源：


type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

看看我們的結構描述，PostStatus列舉可能有數種狀態。我們可能想要名為 success（已成功處理貼文）、 pending （正在處理貼文）和 error（無法處理貼文）的三個基本狀態。若要新增列舉，我們可以執行下列動作：


enum PostStatus {
  success
  pending
  error
}

完整的結構描述可能如下所示：


schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts: [Post]
}

enum PostStatus {  
  success
  pending
  error
}

如果使用者Post在應用程式中新增，則會呼叫 addPost操作來處理該資料。作為連接 addPost來處理資料的解析器，它會持續更新，poststatus並顯示操作的狀態。查詢時， Post將包含資料的最終狀態。請記住，我們只會描述我們希望資料在結構描述中如何運作。我們正在假設許多有關解析程式的實作（這將實作實際的業務邏輯，以處理資料以滿足請求）。

選用考量 - 訂閱

中的訂閱 AWS AppSync 會叫用為對突變的回應。您可利用結構描述之中的 Subscription 類型及 @aws_subscribe() 指令進行設定，表示哪些變動用於叫用一項以上的訂閱。如需設定訂閱的詳細資訊，請參閱即時資料。

選用考量 - 關係和分頁

假設您在 DynamoDB 資料表中Posts存放了一百萬個資料，而且您想要傳回其中一些資料。不過，上述的範例查詢只會傳回所有文章。您不想在每次提出請求時擷取所有這些內容。相反地，您會想要分頁它們。請對結構描述進行下列變更：

在 getPosts 欄位中，新增兩個輸入引數： nextToken （迭代器）和 limit（迭代限制）。
新增包含 Posts（擷取Post物件清單）和 nextToken（迭代器）欄位的新PostIterator類型。
變更，getPosts使其傳回 PostIterator ，而不是Post物件清單。


schema {
  query: Query
  mutation: Mutation
}

type Post {
  id: ID!
  title: String
  date: AWSDateTime
  poststatus: PostStatus
}

type Mutation {
  addPost(id: ID!, title: String, date: AWSDateTime, poststatus: PostStatus): Post
}

type Query {
  getPosts(limit: Int, nextToken: String): PostIterator
}

enum PostStatus {
  success
  pending
  error
}

type PostIterator {
  posts: [Post]
  nextToken: String
}

此PostIterator類型可讓您傳回Post物件清單的一部分，以及nextToken用於取得下一個部分的。在中PostIterator，有一個項目清單 Post（[Post]）是以分頁權杖（）傳回nextToken。在中 AWS AppSync，這會透過解析器連線至 Amazon DynamoDB，並自動產生為加密權杖。這會將 limit 引數的值轉換成 maxResults 參數，並將 nextToken 引數轉換成 exclusiveStartKey 參數。如需 AWS AppSync 主控台中的範例和內建範本範例，請參閱解析器參考（JavaScript）。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

建構圖形 SQL API (空白或匯入的 API)

連接資料來源