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

使用 Amazon OpenSearch Service 解析程式 in AWS AppSync

AWS AppSync 支援從您在自己的 AWS 帳戶中佈建的網域使用 Amazon OpenSearch Service，前提是這些網域不存在於 VPC 中。在佈建網域之後，您可以使用資料來源來連線到這些網域，此時您可以在結構描述中設定解析程式，來進行 GraphQL 操作，例如查詢、變動和訂閱。本教學課程將會逐步說明一些常見的範例。

如需詳細資訊，請參閱 OpenSearch 的解析程式映射範本參考。

一鍵設定

若要在已設定 Amazon OpenSearch Service 的 AWS AppSync 中自動設定 GraphQL 端點，您可以使用此 AWS CloudFormation 範本：

AWS CloudFormation 部署完成後，您可以直接跳至執行 GraphQL 查詢和變動。

建立新的 OpenSearch Service 網域

若要開始使用本教學課程，您需要現有的 OpenSearch Service 網域。如果尚未擁有，您可以使用下列範例。請注意，建立 OpenSearch Service 網域最多可能需要 15 分鐘，然後才能繼續將其與 an AWS AppSync 資料來源整合。

aws cloudformation create-stack --stack-name AppSyncOpenSearch \
--template-url https://s3.us-west-2.amazonaws.com/awsappsync/resources/elasticsearch/ESResolverCFTemplate.yaml \
--parameters ParameterKey=OSDomainName,ParameterValue=ddtestdomain ParameterKey=Tier,ParameterValue=development \
--capabilities CAPABILITY_NAMED_IAM

您可以在 AWS 帳戶中的美國西部 2 （奧勒岡） 區域啟動下列 AWS CloudFormation 堆疊：

設定 OpenSearch Service 的資料來源

建立 OpenSearch Service 網域後，導覽至 your AWS AppSync GraphQL API，然後選擇資料來源索引標籤。選擇新增並輸入資料來源的易記名稱，例如「oss」。然後選擇資料來源類型的 Amazon OpenSearch 網域，選擇適當的區域，您應該會看到列出的 OpenSearch Service 網域。選取後，您可以建立新的角色，而 AWS AppSync 會指派適當的角色許可，或者您可以選擇具有下列內嵌政策的現有角色：

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "Stmt1234234",
            "Effect": "Allow",
            "Action": [
                "es:ESHttpDelete",
                "es:ESHttpHead",
                "es:ESHttpGet",
                "es:ESHttpPost",
                "es:ESHttpPut"
            ],
            "Resource": [
                "arn:aws:es:REGION:ACCOUNTNUMBER:domain/democluster/*"
            ]
        }
    ]
}

您還需要為該角色設定與 AWS AppSync 的信任關係：

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Service": "appsync.amazonaws.com"
            },
            "Action": "sts:AssumeRole"
        }
    ]
}

此外，OpenSearch Service 網域具有自己的存取政策，您可以透過 Amazon OpenSearch Service 主控台進行修改。您需要新增類似下列的政策，以及 OpenSearch Service 網域的適當動作和資源。請注意，主體將是 AppSync 資料來源角色，如果您讓主控台建立此角色，可以在 IAM 主控台中找到。

JSON

{
    "Version": "2012-10-17",
    "Statement": [
        {
        "Effect": "Allow",
        "Principal": {
            "AWS": "arn:aws:iam::ACCOUNTNUMBER:role/service-role/APPSYNC_DATASOURCE_ROLE"
        },
        "Action": [
            "es:ESHttpDelete",
            "es:ESHttpHead",
            "es:ESHttpGet",
            "es:ESHttpPost",
            "es:ESHttpPut"
        ],
        "Resource": "arn:aws:es:REGION:ACCOUNTNUMBER:domain/DOMAIN_NAME/*"
        }
    ]
}

連結解析程式

現在資料來源已連接至 OpenSearch Service 網域，您可以使用解析程式將其連接至 GraphQL 結構描述，如下列範例所示：

 schema {
   query: Query
   mutation: Mutation
 }

 type Query {
   getPost(id: ID!): Post
   allPosts: [Post]
 }

 type Mutation {
   addPost(id: ID!, author: String, title: String, url: String, ups: Int, downs: Int, content: String): AWSJSON
 }

type Post {
  id: ID!
  author: String
  title: String
  url: String
  ups: Int
  downs: Int
  content: String
}
...

請注意，有使用者定義的 Post 類型與 id 欄位。在下列範例中，我們假設有一個程序 （可自動化） 可將此類型放入您的 OpenSearch Service 網域，這會對應至路徑根 /post/_doc，其中 post是索引。在此根路徑中，您可以執行個別文件搜尋、使用 進行萬用字元搜尋/id/post*，或使用 的路徑進行多文件搜尋/post/_search。例如，如果您有另一種名為 的類型User，您可以在名為 的新索引下為文件編製索引user，然後使用路徑 執行搜尋/user/_search。

從 AWS AppSync 主控台的結構描述編輯器中，修改先前的Posts結構描述以包含searchPosts查詢：

type Query {
  getPost(id: ID!): Post
  allPosts: [Post]
  searchPosts: [Post]
}

儲存結構描述。在右側的 searchPosts 中，選擇 Attach resolver (附加解析程式)。在動作功能表中，選擇更新執行時間，然後選擇單位解析程式 （僅限 VTL)。然後，選擇您的 OpenSearch Service 資料來源。在 request mapping template (請求映射範本) 區段中，選取 Query posts (查詢文章) 的下拉式清單，來取得基本範本。將 path 修改為 /post/_search。它看起來應該如下所示：

{
    "version":"2017-02-28",
    "operation":"GET",
    "path":"/post/_search",
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "from":0,
            "size":50
        }
    }
}

這會假設上述結構描述的文件已在 OpenSearch Service 的 post 欄位下編製索引。如果您建立的資料結構不同，將會需要進行對應的更新。

在回應映射範本區段下，如果您想要從 OpenSearch Service 查詢取得資料結果並轉譯為 GraphQL，則需要指定適當的_source篩選條件。使用下列的範本：

[
    #foreach($entry in $context.result.hits.hits)
    #if( $velocityCount > 1 ) , #end
    $utils.toJson($entry.get("_source"))
    #end
]

修改您的搜尋

前述的請求映射範本，會針對所有記錄執行簡單的查詢。假設您想要根據特定的作者來進行搜尋。此外，假設您希望該位作者成為 GraphQL 查詢中所定義的引數。在 AWS AppSync 主控台的結構描述編輯器中，新增allPostsByAuthor查詢：

type Query {
  getPost(id: ID!): Post
  allPosts: [Post]
  allPostsByAuthor(author: String!): [Post]
  searchPosts: [Post]
}

現在選擇連接解析程式，然後選取 OpenSearch Service 資料來源，但在回應映射範本中使用下列範例：

{
    "version":"2017-02-28",
    "operation":"GET",
    "path":"/post/_search",
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "from":0,
            "size":50,
            "query":{
                "match" :{
                    "author": $util.toJson($context.arguments.author)
                }
            }
        }
    }
}

請注意，body 會填入 author 欄位的查詢詞語，此欄位會做為引數，從用戶端直接傳來。您可以選擇性地預先填入資訊 (例如標準的文字內容)，或甚至使用其他公用程式。

如果您正在使用此解析程式，請使用與先前範例相同的資訊，來填寫回應映射範本。

將資料新增至 OpenSearch Service

由於 GraphQL 變動，您可能想要將資料新增至 OpenSearch Service 網域。這是一個具有搜尋和其他用途的強大機制。由於您可以使用 GraphQL 訂閱讓資料即時，因此它可做為通知用戶端 OpenSearch Service 網域中資料更新的機制。

返回 AWS AppSync 主控台中的結構描述頁面，並為addPost()變動選取連接解析程式。再次選取 OpenSearch Service Posts 資料來源，並針對結構描述使用以下回應映射範本：

{
    "version":"2017-02-28",
    "operation":"PUT",
    "path": $util.toJson("/post/_doc/$context.arguments.id"),
    "params":{
        "headers":{},
        "queryString":{},
        "body":{
            "id": $util.toJson($context.arguments.id),
            "author": $util.toJson($context.arguments.author),
            "ups": $util.toJson($context.arguments.ups),
            "downs": $util.toJson($context.arguments.downs),
            "url": $util.toJson($context.arguments.url),
            "content": $util.toJson($context.arguments.content),
            "title": $util.toJson($context.arguments.title)
        }
    }
}

和之前相同，這是如何建構資料結構的一個範例。如果有不同的欄位名稱或索引，您需要適當地更新 path 與 body。此範例也示範了如何利用 $context.arguments，以 GraphQL 變動引數來填寫範本。

在繼續之前，請使用下列回應映射範本，這會傳回變動操作的結果或錯誤資訊做為輸出：

#if($context.error)
    $util.toJson($ctx.error)
#else
    $util.toJson($context.result)
#end

擷取單一文件

最後，如果您想要在結構描述中使用getPost(id:ID)查詢來傳回個別文件，請在 AWS AppSync 主控台的結構描述編輯器中尋找此查詢，然後選擇連接解析程式。再次選取 OpenSearch Service 資料來源，並使用下列映射範本：

{
    "version":"2017-02-28",
    "operation":"GET",
    "path": $util.toJson("post/_doc/$context.arguments.id"),
    "params":{
        "headers":{},
        "queryString":{},
        "body":{}
    }
}

由於上述的 path 使用 id 引數與空的內容，因此這會傳回空的單一文件。不過，因為現在傳回的是單一項目而非清單，您需要使用下列回應映射範本：

$utils.toJson($context.result.get("_source"))

執行查詢與變動

您現在應該能夠對 OpenSearch Service 網域執行 GraphQL 操作。導覽至 AWS AppSync 主控台的查詢索引標籤，並新增記錄：

mutation addPost {
    addPost (
        id:"12345"
        author: "Fred"
        title: "My first book"
        content: "This will be fun to write!"
        url: "publisher website",
        ups: 100,
        downs:20 
       )
}

您會在右側看到變動的結果。同樣地，您現在可以針對 OpenSearch Service 網域執行searchPosts查詢：

query searchPosts {
    searchPosts {
        id
        title
        author
        content
    }
}

最佳實務