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

# 將 Amazon CloudSearch 與 API Gateway 整合
<a name="api-gateway"></a>

本章提供有關將 Amazon CloudSearch 與 Amazon API Gateway 整合的資訊。API Gateway 可讓您建立和託管 REST APIs以呼叫其他 服務。搭配 Amazon CloudSearch 使用 API Gateway 的一些使用案例包括下列項目：
+ 使用 API 金鑰或 Amazon Cognito 使用者集區進一步保護 Amazon CloudSearch 搜尋端點 Amazon Cognito 
+ 使用 CloudWatch 監控和記錄對 Amazon CloudSearch 網域的搜尋呼叫
+ 將使用者限制為更有限的 Amazon CloudSearch API 子集
+ 針對請求數量強制執行速率限制

若要進一步了解 API Gateway 的優點，請參閱 [API Gateway 開發人員指南](https://docs.aws.amazon.com/apigateway/latest/developerguide/)。

**Topics**
+ [先決條件](#api-gateway-pre)
+ [建立與設定 API (主控台)](#api-gateway-create)
+ [測試 API (主控台)](#api-gateway-test)

## 先決條件
<a name="api-gateway-pre"></a>

將 Amazon CloudSearch 與 API Gateway 整合之前，您必須擁有下列資源。


****  

| 先決條件  | Description | 
| --- | --- | 
| Amazon CloudSearch 網域 | 為了測試目的，網域應該有一些可搜尋的資料。IMDb 電影資料是絕佳的選項。<br />網域必須有以下存取政策：<br />此政策會設定 Amazon CloudSearch 網域，以便只有 API Gateway （也可能是帳戶擁有者） 可以存取它。若要進一步了解，請參閱 [建立 Amazon CloudSearch 網域](creating-domains.md)和[設定 Amazon CloudSearch 的存取](configuring-access.md)。 | 
| IAM 角色 | 此角色會將許可委派給 API Gateway，並允許其向 Amazon CloudSearch 提出請求。此章中的角色稱為 `{{my-api-gateway-role}}`，並且必須擁有以下權限：  JSON   

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [{
    "Effect": "Allow",
    "Action": [
      "logs:CreateLogGroup",
      "logs:CreateLogStream",
      "logs:DescribeLogGroups",
      "logs:DescribeLogStreams",
      "logs:PutLogEvents",
      "logs:GetLogEvents",
      "logs:FilterLogEvents"
    ],
    "Resource": "*"
  }]
}
```    <br />此角色也必須具有下列信任關係：  JSON   

****  

```
{
  "Version":"2012-10-17",		 	 	 
  "Statement": [{
    "Sid": "",
    "Effect": "Allow",
    "Principal": {
      "Service": "apigateway.amazonaws.com"
    },
    "Action": "sts:AssumeRole"
  }]
}
```    <br />若要進一步了解，請參閱《*IAM 使用者指南*》中的[建立角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html)。 | 

## 建立與設定 API (主控台)
<a name="api-gateway-create"></a>

依據請求是否使用參數、需要請求內文、需要特定標頭，以及許多其他因素而定，建立 API 的步驟將有所不同。下列程序會建立具有一個 函數的 API：在 Amazon CloudSearch 網域上執行搜尋。如需設定 APIs的詳細資訊，請參閱[在 Amazon API Gateway 中建立 API](https://docs.aws.amazon.com/apigateway/latest/developerguide/how-to-create-api.html)。

**建立 API (主控台)**

1. 登入 AWS 管理主控台，並在 https：//[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway) 開啟 API Gateway 主控台。

1. 選擇**建立 API** （如果這是您第一次使用 API Gateway，請選擇**開始使用**)。

1. 在 **REST API** 下選擇**建置** （非私有）。

1. 提供名稱和選用描述，然後選擇**建立 API**。

1. 選擇**動作**、**建立方法**。從下拉式功能表中，選擇 **GET** 並確認。

1. 針對 **Integration type** (整合類型)，選擇 **AWS Service** (AWS 服務)。

1. 針對**AWS 區域**，選擇 Amazon CloudSearch 網域所在的區域。

1. 針對**AWS 服務**，選擇 **CloudSearch**。

1. 針對**AWS 子網域**，指定 Amazon CloudSearch 網域搜尋端點的子網域。

   例如，如果網域的搜尋端點是 `search-my-test-asdf5asdfasdfasdfasd5asdfg.us-west-1.cloudsearch.amazonaws.com`，請指定 `search-my-test-asdf5ambgebbgmmodhhq5asdfg`。

1. 針對 **HTTP Method (HTTP 方法)**，選擇 **GET**。

1. 針對**動作類型**，選擇**使用路徑覆寫**，然後輸入 `/2013-01-01/search`。

1. 針對 **Execution role (執行角色)**，請指定 `{{my-api-gateway-role}}` 的 ARN，例如 `arn:aws:iam::{{123456789012}}:role/{{my-api-gateway-role}}`。

1. 針對 **Content Handling (內容處理)**，選擇 **Passthrough (傳遞)**，使用預設的逾時，然後選擇 **Save (儲存)**。

1. 選擇 **Method Request (方法請求)**。

1. 針對 **Request Validator (請求驗證程式)**，請選擇 **Validate query string parameters and headers (驗證查詢字串參數和標頭)**，然後確認。

1. 展開 **URL Query String Parameters (URL 查詢字串參數)**。選擇**新增查詢字串**，將字串命名為 `q`，然後確認。視需要標記查詢字串。

1. 選擇 **Method Execution (方法執行)** 以返回方法摘要。

1. 選擇 **Integration Request (整合請求)**。

1. 展開 **URL Query String Parameters (URL 查詢字串參數)**。選擇**新增查詢字串**、命名字串 `q`、提供 的映射`method.request.querystring.q`，然後確認。

## 測試 API (主控台)
<a name="api-gateway-test"></a>

此時，您已建立擁有一個方法的 API。在部署 API 之前，您應進行 API 測試。

**測試 API (主控台)**

1. 導覽至 **Method Execution (方法執行)** 頁面。

1. 選擇**測試**。

1. 在**查詢字串**下，輸入符合 Amazon CloudSearch 網域中部分資料的查詢字串。如果您使用 IMDb 電影資料，請嘗試 `q=thor`。

1. 選擇**測試**。

1. 確認回應內文包含搜尋結果，例如：

   ```
   {
     "status": {
       "rid": "rcWTo8IsviEK+own",
       "time-ms": 1
     },
     "hits": {
       "found": 7,
       "start": 0,
       "hit": [
         {
           "id": "tt0800369",
           "fields": {
             "rating": "7.0",
             "genres": [
               "Action",
               "Adventure",
               "Fantasy"
             ],
             "title": "Thor",
             "release_date": "2011-04-21T00:00:00Z",
             "plot": "The powerful but arrogant god Thor is cast out of Asgard to live amongst humans in Midgard (Earth), where he soon becomes one of their finest defenders.",
             "rank": "135",
             "running_time_secs": "6900",
             "directors": [
               "Kenneth Branagh",
               "Joss Whedon"
             ],
             "image_url": "http://ia.media-imdb.com/images/M/MV5BMTYxMjA5NDMzNV5BMl5BanBnXkFtZTcwOTk2Mjk3NA@@._V1_SX400_.jpg",
             "year": "2011",
             "actors": [
               "Chris Hemsworth",
               "Anthony Hopkins",
               "Natalie Portman"
             ]
           }
         },
         {{...}}
       ]
     }
   }
   ```

現在，您已擁有一個可正常運作的 API。您可以新增方法來啟用更強大的搜尋請求、部署 API 並設定速率限制、建立和要求使用 API 金鑰、新增 Amazon Cognito 使用者集區身分驗證等等。如需詳細資訊，請參閱 [API Gateway 開發人員指南](https://docs.aws.amazon.com/apigateway/latest/developerguide/)。