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

# 教學課程：建立 REST API 做為 Amazon Kinesis 代理
<a name="integrating-api-with-aws-services-kinesis"></a>

本頁面說明如何建立和設定與 `AWS` 類型整合的 REST API，以存取 Kinesis。

**注意**  
 若要整合 API Gateway API 與 Kinesis，您必須選擇可使用 API Gateway API 與 Kinesis 服務的區域。如需區域可用性，請參閱[服務端點和配額](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html)。

 基於說明，我們建立範例 API，讓用戶端執行下列操作：

1. 列出 Kinesis 中的使用者可用串流 

1. 建立、說明或刪除指定的串流

1. 從指定的串流讀取資料記錄或將資料記錄寫入其中

 為了達成先前的任務，API 會分別公開各種資源的方法來呼叫下列項目：

1. Kinesis 中的 `ListStreams` 動作 

1. `CreateStream`、`DescribeStream` 或 `DeleteStream` 動作

1. Kinesis 中的 `GetRecords` 或 `PutRecords` (包含 `PutRecord`) 動作

 具體而言，我們會如下建置 API：
+  在 API `/streams` 資源上公開 HTTP GET 方法，並在 Kinesis 中整合此方法與 [ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html) 動作，以列出發起人帳戶中的串流。
+  在 API `/streams/{stream-name}` 資源上公開 HTTP POST 方法，並在 Kinesis 中整合此方法與 [CreateStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_CreateStream.html) 動作，以在發起人帳戶中建立具名串流。
+  在 API `/streams/{stream-name}` 資源上公開 HTTP GET 方法，並在 Kinesis 中整合此方法與 [DescribeStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DescribeStream.html) 動作，以說明發起人帳戶中的具名串流。
+  在 API `/streams/{stream-name}` 資源上公開 HTTP DELETE 方法，並在 Kinesis 中整合此方法與 [DeleteStream](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_DeleteStream.html) 動作，以刪除發起人帳戶中的串流。
+  在 API 的 `/streams/{stream-name}/record` 資源上公開 HTTP PUT 方法，並在 Kinesis 中整合此方法與 [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html) 動作。這可讓用戶端將單一資料記錄新增至具名串流。
+  在 API 的 `/streams/{stream-name}/records` 資源上公開 HTTP PUT 方法，並在 Kinesis 中整合此方法與 [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html) 動作。這可讓用戶端將資料記錄清單新增至具名串流。
+  在 API `/streams/{stream-name}/records` 資源上公開 HTTP GET 方法，並在 Kinesis 中整合此方法與 [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html) 動作。這可讓用戶端使用指定的碎片迭代運算來列出具名串流中的資料記錄。碎片迭代運算指定從中循序開始讀取資料記錄的碎片位置。
+  在 API `/streams/{stream-name}/sharditerator` 資源上公開 HTTP GET 方法，並在 Kinesis 中整合此方法與 [GetShardIterator](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html) 動作。必須向 Kinesis 中的 `ListStreams` 動作提供此 helper 方法。

 您可以將這裡看到的說明套用至其他 Kinesis 動作。如需完整 Kinesis 動作清單，請參閱 [Amazon Kinesis API 參考](https://docs.aws.amazon.com/kinesis/latest/APIReference/Welcome.html)。

 除了使用 API Gateway 主控台來建立範例 API 之外，您還可以使用 API Gateway​ [Import API](https://docs.aws.amazon.com/apigateway/latest/api/API_ImportRestApi.html)，以將範例 API 匯入至 API Gateway。如需如何使用 Import API 的資訊，請參閱「[在 API Gateway 中使用 OpenAPI 開發 REST API](api-gateway-import-api.md)」。

## 建立 API 的 IAM 角色和政策來存取 Kinesis
<a name="integrate-with-kinesis-create-iam-role-and-policy"></a>

 若要允許 API 叫用 Kinesis 動作，您必須將適當的 IAM 政策附加至 IAM 角色。在此步驟中，您會建立新的 IAM 角色。

**建立 AWS 服務代理執行角色**

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

1. 選擇**角色**。

1. 選擇建**立角色**。

1.  在**選取信任的實體類型**下選擇 **AWS 服務**，然後選取 **API Gateway** 並選取**允許 API Gateway 將日誌推送到 CloudWatch Logs**。

1.  選擇**下一步**，然後選擇**下一步**。

1. 針對**角色名稱**，輸入 **APIGatewayKinesisProxyPolicy**，然後選擇**建立角色**。

1. 在**角色**清單中，選擇您剛剛建立的角色。您可能需要捲動或使用搜尋列來尋找該角色。

1. 針對選取的角色，選取 **許可** 索引標籤。

1. 在下拉式清單中，選擇 **連接政策**。

1. 在搜尋列中輸入 **AmazonKinesisFullAccess**，並選擇**新增許可**。
**注意**  
本教學課程為了簡單起見，使用受管理政策。最佳實務是，您應建立自己的 IAM 政策以授予所需的最低許可。

1. 記下新建的**角色 ARN**，以在稍後使用。

## 建立 API 以做為 Kinesis 代理
<a name="api-gateway-create-api-as-kinesis-proxy"></a>

使用下列步驟可在 API Gateway 主控台中建立 API。

**建立 API 做為 Kinesis AWS 的服務代理**

1. 在以下網址登入 API Gateway 主控台：[https://console.aws.amazon.com/apigateway](https://console.aws.amazon.com/apigateway)。

1. 如果這是您第一次使用 API Gateway，您會看到服務功能的介紹頁面。在 **REST API** 下方，選擇 **Build (組建)**。當 **Create Example API (建立範例 API)** 快顯出現時，選擇 **OK (確定)**。

   如果這不是第一次使用 API Gateway，請選擇 **Create API (建立 API)**。在 **REST API** 下方，選擇 **Build (組建)**。

1. 選擇 **New API (新增 API)**。

1. 在 **API name (API 名稱)** 中，輸入 **KinesisProxy**。對於所有其他欄位，請保留預設值。

1. 在**描述**，請輸入描述。

1. 針對 **IP 位址類型**，選擇 **IPv4**。

1. 選擇 **Create API (建立 API)**。

 建立 API 之後，API Gateway 主控台會顯示 **Resources (資源)** 頁面，其中只包含 API 的根 (`/`) 資源。

## 列出 Kinesis 中的串流
<a name="api-gateway-list-kinesis-streams"></a>

 Kinesis 透過下列 REST API 呼叫來支援 `ListStreams` 動作：

```
POST /?Action=ListStreams HTTP/1.1
Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>
        
{
   ...
}
```

在上面的 REST API 請求中，動作指定於 `Action` 查詢參數中。或者，您可以改為在 `X-Amz-Target` 標頭中指定動作：

```
POST / HTTP/1.1
Host: kinesis.<region>.<domain>
Content-Length: <PayloadSizeBytes>
User-Agent: <UserAgentString>
Content-Type: application/x-amz-json-1.1
Authorization: <AuthParams>
X-Amz-Date: <Date>
X-Amz-Target: Kinesis_20131202.ListStreams        
{
   ...
}
```

在本教學中，我們使用查詢參數來指定動作。

若要在 API 中公開 Kinesis 動作，請將 `/streams` 資源新增至 API 根。然後在資源上設定 `GET` 方法，並整合此方法與 Kinesis 的 `ListStreams` 動作。

下列程序說明如何使用 API Gateway 主控台來列出 Kinesis 串流。

**使用 API Gateway 主控台來列出 Kinesis 串流**

1. 選取 `/` 資源，然後選擇**建立資源**。

1. 針對**資源名稱**，輸入 **streams**。

1. 讓 **CORS (跨來源資源分享)** 保持關閉。

1. 選擇**建立資源**。

1.  選擇 `/streams` 資源，然後選擇**建立方法**，然後執行下列動作：

   1. 針對**方法類型**，選取 **GET**。
**注意**  
用戶端所呼叫方法的 HTTP 動詞可能會與後端所需整合的 HTTP 動詞不同。我們在這裡選取 `GET`，因為列出串流直覺上就是 READ 操作。

   1. 針對**整合類型**，選取 **AWS 服務**。

   1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

   1. 針對 **AWS 服務**，選取 **Kinesis**。

   1. 讓 **AWS 子網域**保持空白。

   1. 針對 **HTTP method (HTTP 方法)**，選擇 **POST**。
**注意**  
我們在這裡選擇 `POST`，因為 Kinesis 需要使用它來叫用 `ListStreams` 動作。

   1. 針對**動作類型**，選擇**使用動作名稱**。

   1. 針對**動作名稱**，輸入 **ListStreams**。

   1. 針對**執行角色**，輸入執行角色的 ARN。

   1. 保留**內容處理**之**傳遞**的預設值。

   1. 選擇**建立方法**。

1. 在**整合請求**索引標籤上，於**整合請求設定**下，選擇**編輯**。

1. 針對**請求內文傳遞**，選取**未定義範本時 (建議)**。

1.  選擇 **URL 請求標頭參數**，然後執行下列動作：

   1. 選擇**新增請求標頭參數**。

   1. 對於**名稱**，輸入 **Content-Type**。

   1. 對於**映射自**，輸入 **'application/x-amz-json-1.1'**。

    我們會使用請求參數對應將 `Content-Type` 標頭設定為靜態值 `'application/x-amz-json-1.1'`，通知 Kinesis 有關輸入是特定版本的 JSON。

1. 選擇**對應範本**，然後選擇**新增對應範本**，並執行下列動作：

   1. 針對 **Content-Type**，輸入 **application/json**。

   1. 針對**範本內文**，輸入 **\$1\$1**。

   1. 選擇**儲存**。

    [ListStreams](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_ListStreams.html#API_ListStreams_RequestSyntax) 請求採用下列 JSON 格式的承載：

   ```
   {
       "ExclusiveStartStreamName": "string",
       "Limit": number
   }
   ```

   不過，屬性是選用的。若要使用預設值，我們在這裡選擇空的 JSON 承載。

1. 測試 **/streams** 資源上的 GET 方法，以在 Kinesis 中叫用 `ListStreams` 動作：

   選擇**測試**標籤。您可能需要選擇向右箭頭按鈕才能顯示此索引標籤。

   選擇**測試**以測試您的方法。

    如果您已經在 Kinesis 中建立兩個名為 "myStream" 和 "yourStream" 的串流，則成功測試會傳回包含下列承載的 200 OK 回應：

   ```
   {
        "HasMoreStreams": false,
        "StreamNames": [
            "myStream",
            "yourStream"
        ]
   }
   ```

## 在 Kinesis 中建立、說明和刪除串流
<a name="api-gateway-create-describe-delete-stream"></a>

 在 Kinesis 中建立、說明和刪除串流會分別進行下列 Kinesis REST API 請求：

```
POST /?Action=CreateStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "ShardCount": number,
    "StreamName": "string"
}
```

```
POST /?Action=DescribeStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "StreamName": "string"
}
```

```
POST /?Action=DeleteStream HTTP/1.1
Host: kinesis.region.domain
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "StreamName":"string"
}
```

 我們可以建置 API 以接受所需的輸入做為方法請求的 JSON 承載，並將承載傳遞至整合請求。不過，若要提供方法與整合請求之間以及方法與整合回應之間的更多資料對應範例，我們會建立略為不同的 API。

 我們會對指定的 `GET` 資源公開 `POST`、`Delete` 和 `Stream` HTTP 方法。我們使用 `{stream-name}` 路徑變數做為串流資源的預留位置，並分別整合這些 API 方法與 Kinesis 的 `DescribeStream`、`CreateStream` 和 `DeleteStream` 動作。我們需要用戶端將其他輸入資料傳遞為方法請求的標頭、查詢參數或承載。我們提供對應範本將資料轉換為所需的整合請求承載。

**建立 \$1stream-name\$1 資源**

1. 選擇 **/streams** 資源，然後選擇**建立資源**。

1. 讓**代理資源**保持關閉。

1. 針對**資源路徑**，選取 `/streams`。

1. 針對**資源名稱**，輸入 **\$1stream-name\$1**。

1. 讓 **CORS (跨來源資源分享)** 保持關閉。

1. 選擇**建立資源**。

**設定和測試串流資源上的 GET 方法**

1. 選擇 **/\$1stream-name\$1** 資源，然後選擇**建立方法**。

1. 針對**方法類型**，選取 **GET**。

1. 針對**整合類型**，選取 **AWS 服務**。

1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

1. 針對 **AWS 服務**，選取 **Kinesis**。

1. 讓 **AWS 子網域**保持空白。

1. 針對 **HTTP 方法**，請選擇 **POST**。

1. 針對**動作類型**，選擇**使用動作名稱**。

1. 針對**動作名稱**，輸入 **DescribeStream**。

1. 針對**執行角色**，輸入執行角色的 ARN。

1. 保留**內容處理**之**傳遞**的預設值。

1. 選擇**建立方法**。

1. 在**整合請求**區段中，新增下列 **URL 請求標頭參數**：

   ```
   Content-Type: 'x-amz-json-1.1'
   ```

   任務所遵循的程序與設定 `GET /streams` 方法的請求參數映射相同。

1. 新增下列內文對應範本，以將資料從 `GET /streams/{stream-name}` 方法請求對應至 `POST /?Action=DescribeStream` 整合請求：

   ```
   {
       "StreamName": "$input.params('stream-name')"
   }
   ```

   此對應範本會透過方法請求的 `DescribeStream` 路徑參數值，來產生 Kinesis 之 `stream-name` 動作所需的整合請求承載。

1. 若要測試在 Kinesis 中叫用 `DescribeStream` 動作的 `GET /stream/{stream-name}` 方法，請選擇**測試**索引標籤。

1. 針對**路徑**，在 **stream-name** 下，輸入現有 Kinesis 串流的名稱。

1. 選擇**測試**。如果測試成功，則會傳回承載與類似下列的 200 OK 回應：

   ```
   {
     "StreamDescription": {
       "HasMoreShards": false,
       "RetentionPeriodHours": 24,
       "Shards": [
         {
           "HashKeyRange": {
             "EndingHashKey": "68056473384187692692674921486353642290",
             "StartingHashKey": "0"
           },
           "SequenceNumberRange": {
             "StartingSequenceNumber": "49559266461454070523309915164834022007924120923395850242"
           },
           "ShardId": "shardId-000000000000"
         },
         ...
         {
           "HashKeyRange": {
             "EndingHashKey": "340282366920938463463374607431768211455",
             "StartingHashKey": "272225893536750770770699685945414569164"
           },
           "SequenceNumberRange": {
             "StartingSequenceNumber": "49559266461543273504104037657400164881014714369419771970"
           },
           "ShardId": "shardId-000000000004"
         }
       ],
       "StreamARN": "arn:aws:kinesis:us-east-1:12345678901:stream/myStream",
       "StreamName": "myStream",
       "StreamStatus": "ACTIVE"
     }
   }
   ```

    在您部署 API 之後，可以針對此 API 方法提出 REST 請求：

   ```
   GET https://your-api-id.execute-api.region.amazonaws.com/stage/streams/myStream HTTP/1.1
   Host: your-api-id.execute-api.region.amazonaws.com
   Content-Type: application/json
   Authorization: ...
   X-Amz-Date: 20160323T194451Z
   ```

**設定和測試串流資源上的 POST 方法**

1. 選擇 **/\$1stream-name\$1** 資源，然後選擇**建立方法**。

1. 針對**方法類型**，選取 **POST**。

1. 針對**整合類型**，選取 **AWS 服務**。

1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

1. 針對 **AWS 服務**，選取 **Kinesis**。

1. 讓 **AWS 子網域**保持空白。

1. 針對 **HTTP 方法**，請選擇 **POST**。

1. 針對**動作類型**，選擇**使用動作名稱**。

1. 針對**動作名稱**，輸入 **CreateStream**。

1. 針對**執行角色**，輸入執行角色的 ARN。

1. 保留**內容處理**之**傳遞**的預設值。

1. 選擇**建立方法**。

1. 在**整合請求**區段中，新增下列 **URL 請求標頭參數**：

   ```
   Content-Type: 'x-amz-json-1.1'
   ```

   任務所遵循的程序與設定 `GET /streams` 方法的請求參數映射相同。

1.  新增下列內文對應範本，以將資料從 `POST /streams/{stream-name}` 方法請求對應至 `POST /?Action=CreateStream` 整合請求：

   ```
   {
       "ShardCount": #if($input.path('$.ShardCount') == '') 5 #else $input.path('$.ShardCount') #end,
       "StreamName": "$input.params('stream-name')"
   }
   ```

    如果用戶端未在方法請求承載中指定值，則在先前的對應範本中，我們將 `ShardCount` 設定為固定值 5。

1. 若要測試在 Kinesis 中叫用 `CreateStream` 動作的 `POST /stream/{stream-name}` 方法，請選擇**測試**索引標籤。

1. 針對**路徑**，在 **stream-name** 下，輸入新 Kinesis 串流的名稱。

1. 選擇**測試**。如果測試成功，則會傳回 200 OK 回應，而沒有資料。

    在您部署 API 之後，也可以對串流資源上的 POST 方法提出 REST API 請求，以在 Kinesis 中叫用 `CreateStream` 動作：

   ```
   POST https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
   Host: your-api-id.execute-api.region.amazonaws.com
   Content-Type: application/json
   Authorization: ...
   X-Amz-Date: 20160323T194451Z
   
   { 
       "ShardCount": 5
   }
   ```

**設定和測試串流資源上的 DELETE 方法**

1. 選擇 **/\$1stream-name\$1** 資源，然後選擇**建立方法**。

1. 針對**方法類型**，選取 **DELETE**。

1. 針對**整合類型**，選取 **AWS 服務**。

1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

1. 針對 **AWS 服務**，選取 **Kinesis**。

1. 讓 **AWS 子網域**保持空白。

1. 針對 **HTTP 方法**，請選擇 **POST**。

1. 針對**動作類型**，選擇**使用動作名稱**。

1. 針對**動作名稱**，輸入 **DeleteStream**。

1. 針對**執行角色**，輸入執行角色的 ARN。

1. 保留**內容處理**之**傳遞**的預設值。

1. 選擇**建立方法**。

1. 在**整合請求**區段中，新增下列 **URL 請求標頭參數**：

   ```
   Content-Type: 'x-amz-json-1.1'
   ```

   任務所遵循的程序與設定 `GET /streams` 方法的請求參數映射相同。

1.  新增下列內文對應範本，以將資料從 `DELETE /streams/{stream-name}` 方法請求對應至對應的 `POST /?Action=DeleteStream` 整合請求：

   ```
   {
       "StreamName": "$input.params('stream-name')"
   }
   ```

    此對應範本會從 `DELETE /streams/{stream-name}` 中由用戶端提供的 URL 路徑名稱，產生 `stream-name` 動作的所需輸入。

1. 若要測試在 Kinesis 中叫用 `DeleteStream` 動作的 `DELETE /stream/{stream-name}` 方法，請選擇**測試**索引標籤。

1. 針對**路徑**，在 **stream-name** 下，輸入現有 Kinesis 串流的名稱。

1. 選擇**測試**。如果測試成功，則會傳回 200 OK 回應，而沒有資料。

    在您部署 API 之後，也可以對串流資源上的 DELETE 方法提出下列 REST API 請求，以在 Kinesis 中呼叫 `DeleteStream` 動作：

   ```
   DELETE https://your-api-id.execute-api.region.amazonaws.com/stage/streams/yourStream HTTP/1.1
   Host: your-api-id.execute-api.region.amazonaws.com
   Content-Type: application/json
   Authorization: ...
   X-Amz-Date: 20160323T194451Z
   
   {}
   ```

## 取得 Kinesis 中串流的記錄，並將記錄新增至其中
<a name="api-gateway-get-and-add-records-to-stream"></a>

 在您於 Kinesis 中建立串流之後，可以將資料記錄新增至串流，並讀取串流中的資料。新增資料記錄包含在 Kinesis 中呼叫 [PutRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecords.html#API_PutRecords_Examples) 或 [PutRecord](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_PutRecord.html#API_PutRecord_Examples) 動作。前者會新增多筆記錄，而後者將單一記錄新增至串流。

```
POST /?Action=PutRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "Records": [
        {
            "Data": blob,
            "ExplicitHashKey": "string",
            "PartitionKey": "string"
        }
    ],
    "StreamName": "string"
}
```

或

```
POST /?Action=PutRecord HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "Data": blob,
    "ExplicitHashKey": "string",
    "PartitionKey": "string",
    "SequenceNumberForOrdering": "string",
    "StreamName": "string"
}
```

 在這裡，`StreamName` 識別要新增記錄的目標串流。`StreamName`、`Data` 和 `PartitionKey` 是必要輸入資料。在範例中，我們使用所有選用輸入資料的預設值，因此將不會在方法請求輸入中明確指定其值。

 讀取 Kinesis 數量中的資料以呼叫 [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html#API_GetRecords_Examples) 動作：

```
POST /?Action=GetRecords HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes

{
    "ShardIterator": "string",
    "Limit": number
}
```

在這裡，從中取得記錄的來源串流指定於所需 `ShardIterator` 值，如可取得碎片迭代運算的下列 Kinesis 動作所示：

```
POST /?Action=GetShardIterator HTTP/1.1
Host: kinesis.region.domain
Authorization: AWS4-HMAC-SHA256 Credential=..., ...
...
Content-Type: application/x-amz-json-1.1
Content-Length: PayloadSizeBytes
                
{
    "ShardId": "string",
    "ShardIteratorType": "string",
    "StartingSequenceNumber": "string",
    "StreamName": "string"
}
```

 針對 `GetRecords` 和 `PutRecords` 動作，我們分別在附加至具名串流資源 (`GET`) 的 `PUT` 資源上公開 `/records` 和 `/{stream-name}` 方法。同樣地，我們將 `PutRecord` 動作公開為 `PUT` 資源上的 `/record` 方法。

 因為 `GetRecords` 動作將呼叫 `ShardIterator` helper 動作所取得的 `GetShardIterator` 值採用為輸入，所以我們在 `GET` 資源上公開 `ShardIterator` helper 方法 (`/sharditerator`)。

**建立 /record、/records 和 /sharditerator 資源**

1. 選擇 **/\$1stream-name\$1** 資源，然後選擇**建立資源**。

1. 讓**代理資源**保持關閉。

1. 針對**資源路徑**，選取 `/{stream-name}`。

1. 針對**資源名稱**，輸入 **record**。

1. 讓 **CORS (跨來源資源分享)** 保持關閉。

1. 選擇**建立資源**。

1. 重複前面的步驟，以建立 **/records** 和 **/sharditerator** 資源。最終 API 應如下所示：

      
![\[建立 API 的 Records:GET|PUT|PUT|GET 方法。\]](http://docs.aws.amazon.com/zh_tw/apigateway/latest/developerguide/images/api-gateway-kinesis-proxy-setup-streams-stream-record-method-new-console.png)

 下列四個程序說明如何設定每種方法、如何將資料從方法請求對應至整合請求，以及如何測試方法。

**設定和測試 `PUT /streams/{stream-name}/record` 方法以在 Kinesis 中叫用 `PutRecord`：**

1. 選擇 **/record**，然後選擇**建立方法**。

1. 針對**方法類型**，選取 **PUT**。

1. 針對**整合類型**，選取 **AWS 服務**。

1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

1. 針對 **AWS 服務**，選取 **Kinesis**。

1. 讓 **AWS 子網域**保持空白。

1. 針對 **HTTP 方法**，請選擇 **POST**。

1. 針對**動作類型**，選擇**使用動作名稱**。

1. 針對**動作名稱**，輸入 **PutRecord**。

1. 針對**執行角色**，輸入執行角色的 ARN。

1. 保留**內容處理**之**傳遞**的預設值。

1. 選擇**建立方法**。

1. 在**整合請求**區段中，新增下列 **URL 請求標頭參數**：

   ```
   Content-Type: 'x-amz-json-1.1'
   ```

   任務所遵循的程序與設定 `GET /streams` 方法的請求參數映射相同。

1.  新增下列內文對應範本，以將資料從 `PUT /streams/{stream-name}/record` 方法請求對應至對應的 `POST /?Action=PutRecord` 整合請求：

   ```
   {
       "StreamName": "$input.params('stream-name')",
       "Data": "$util.base64Encode($input.json('$.Data'))",
       "PartitionKey": "$input.path('$.PartitionKey')"
   }
   ```

    此對應範本假設方法請求承載的格式如下：

   ```
   {
      "Data": "some data",
      "PartitionKey": "some key"
   }
   ```

   此資料可以透過下列 JSON 結構描述建立模型：

   ```
   {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "PutRecord proxy single-record payload",
     "type": "object",
     "properties": {
         "Data": { "type": "string" },
         "PartitionKey": { "type": "string" }
     }
   }
   ```

    您可以建立模型來包含此結構描述，並使用此模型來促進產生對應範本。不過，您可以產生對應範本，而不使用任何模型。

1.  若要測試 `PUT /streams/{stream-name}/record` 方法，請將 `stream-name` 路徑變數設定為現有串流的名稱，並提供所需格式的承載，然後提交方法請求。成功結果是承載格式如下的 `200 OK `回應：

   ```
   {
     "SequenceNumber": "49559409944537880850133345460169886593573102115167928386",
     "ShardId": "shardId-000000000004"
   }
   ```

**設定和測試 `PUT /streams/{stream-name}/records` 方法以在 Kinesis 中叫用 `PutRecords`**

1. 選擇 **/records** 資源，然後選擇**建立方法**。

1. 針對**方法類型**，選取 **PUT**。

1. 針對**整合類型**，選取 **AWS 服務**。

1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

1. 針對 **AWS 服務**，選取 **Kinesis**。

1. 讓 **AWS 子網域**保持空白。

1. 針對 **HTTP 方法**，請選擇 **POST**。

1. 針對**動作類型**，選擇**使用動作名稱**。

1. 針對**動作名稱**，輸入 **PutRecords**。

1. 針對**執行角色**，輸入執行角色的 ARN。

1. 保留**內容處理**之**傳遞**的預設值。

1. 選擇**建立方法**。

1. 在**整合請求**區段中，新增下列 **URL 請求標頭參數**：

   ```
   Content-Type: 'x-amz-json-1.1'
   ```

   任務所遵循的程序與設定 `GET /streams` 方法的請求參數映射相同。

1.  新增下列對應範本，以將資料從 `PUT /streams/{stream-name}/records` 方法請求對應至對應的 `POST /?Action=PutRecords` 整合請求：

   ```
   {
       "StreamName": "$input.params('stream-name')",
       "Records": [
          #foreach($elem in $input.path('$.records'))
             {
               "Data": "$util.base64Encode($elem.data)",
               "PartitionKey": "$elem.partition-key"
             }#if($foreach.hasNext),#end
           #end
       ]
   }
   ```

   此對應範本假設方法請求承載可以透過下列 JSON 結構描述建立模型：

   ```
   {
     "$schema": "http://json-schema.org/draft-04/schema#",
     "title": "PutRecords proxy payload data",
     "type": "object",
     "properties": {
       "records": {
         "type": "array",
         "items": {
           "type": "object",
           "properties": {
             "data": { "type": "string" },
             "partition-key": { "type": "string" }
           }
         }
       }
     }
   }
   ```

    您可以建立模型來包含此結構描述，並使用此模型來促進產生對應範本。不過，您可以產生對應範本，而不使用任何模型。

   在本教學中，我們使用兩個略為不同的承載格式來說明 API 開發人員可以選擇向用戶端公開後端資料格式，或向用戶端隱藏它。其中一種格式適用於 `PUT /streams/{stream-name}/records` 方法 (上方)。另一種格式用於 `PUT /streams/{stream-name}/record` 方法 (在先前的程序中)。在生產環境中，您應該保持這兩種格式一致。

1. 

    若要測試 `PUT /streams/{stream-name}/records` 方法，請將 `stream-name` 路徑變數設定為現有串流，並提供下列承載，然後提交方法請求。

   ```
   {
       "records": [
           {
               "data": "some data",
               "partition-key": "some key"
           },
           {
               "data": "some other data",
               "partition-key": "some key"
           }
       ]
   }
   ```

   成功結果是承載與下列輸出類似的 200 OK 回應：

   ```
   {
     "FailedRecordCount": 0,
     "Records": [
       {
         "SequenceNumber": "49559409944537880850133345460167468741933742152373764162",
         "ShardId": "shardId-000000000004"
       },
       {
         "SequenceNumber": "49559409944537880850133345460168677667753356781548470338",
         "ShardId": "shardId-000000000004"
       }
     ]
   }
   ```

**設定和測試 `GET /streams/{stream-name}/sharditerator` 方法以在 Kinesis 中叫用 `GetShardIterator`**

`GET /streams/{stream-name}/sharditerator` 方法是 helper 方法，可先獲得必要碎片迭代運算，再呼叫 `GET /streams/{stream-name}/records` 方法。

1. 選擇 **/sharditerator** 資源，然後選擇**建立方法**。

1. 針對**方法類型**，選取 **GET**。

1. 針對**整合類型**，選取 **AWS 服務**。

1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

1. 針對 **AWS 服務**，選取 **Kinesis**。

1. 讓 **AWS 子網域**保持空白。

1. 針對 **HTTP 方法**，請選擇 **POST**。

1. 針對**動作類型**，選擇**使用動作名稱**。

1. 針對**動作名稱**，輸入 **GetShardIterator**。

1. 針對**執行角色**，輸入執行角色的 ARN。

1. 保留**內容處理**之**傳遞**的預設值。

1. 選擇 **URL 查詢字串參數**。

   `GetShardIterator` 動作需要 ShardId 值的輸入。若要傳遞用戶端提供的 `ShardId` 值，我們將 `shard-id` 查詢參數新增至方法請求，如下列步驟所示。

1. 選擇**新增查詢字串**。

1. 對於**名稱**，輸入 **shard-id**。

1. 將**必要**和**快取**保持關閉。

1. 選擇**建立方法**。

1. 在**整合請求**區段中，新增下列對應範本，以從方法請求的 `shard-id` 和 `stream-name` 參數產生 `GetShardIterator` 動作所需的輸入 (`ShardId` 和 `StreamName`)。此外，對應範本也會將 `ShardIteratorType` 設定為 `TRIM_HORIZON` 做為預設值。

   ```
   {
       "ShardId": "$input.params('shard-id')",
       "ShardIteratorType": "TRIM_HORIZON",
       "StreamName": "$input.params('stream-name')"
   }
   ```

1.  使用 API Gateway 主控台中的 **Test (測試)** 選項，輸入現有串流名稱作為 `stream-name` **Path (路徑)** 變數值，並將 `shard-id` **Query string (查詢字串)** 設定為現有 `ShardId` 值 (例如，`shard-000000000004`)，然後選擇 **Test (測試)**。

    成功回應承載與下列輸出類似：

   ```
   {
     "ShardIterator": "AAAAAAAAAAFYVN3VlFy..."
   }
   ```

   記下 `ShardIterator` 值。您需要有它才能從串流取得記錄。

**設定和測試 `GET /streams/{stream-name}/records` 方法，在 Kinesis 中叫用 `GetRecords` 動作**

1. 選擇 **/records** 資源，然後選擇**建立方法**。

1. 針對**方法類型**，選取 **GET**。

1. 針對**整合類型**，選取 **AWS 服務**。

1. 針對 **AWS 區域**，選取您建立 Kinesis 串流 AWS 區域 的 。

1. 針對 **AWS 服務**，選取 **Kinesis**。

1. 讓 **AWS 子網域**保持空白。

1. 針對 **HTTP 方法**，請選擇 **POST**。

1. 針對**動作類型**，選擇**使用動作名稱**。

1. 針對**動作名稱**，輸入 **GetRecords**。

1. 針對**執行角色**，輸入執行角色的 ARN。

1. 保留**內容處理**之**傳遞**的預設值。

1. 選擇 **HTTP 請求標頭**。

    `GetRecords` 動作需要 `ShardIterator` 值的輸入。若要傳遞用戶端提供的 `ShardIterator` 值，我們會將 `Shard-Iterator` 標頭參數新增至方法請求。

1. 選擇**新增標頭**。

1. 對於**名稱**，輸入 **Shard-Iterator**。

1. 將**必要**和**快取**保持關閉。

1. 選擇**建立方法**。

1.  在**整合請求**區段中，新增下列內文對應範本，以將 `Shard-Iterator` 標頭參數值對應至 Kinesis 中 `GetRecords` 動作之 JSON 承載的 `ShardIterator` 屬性值。

   ```
   {
       "ShardIterator": "$input.params('Shard-Iterator')"
   }
   ```

1.  使用 API Gateway 主控台中的**測試**選項，輸入現有串流名稱做為 `stream-name` **路徑**變數值，並將 `Shard-Iterator` **標頭**設定為取自 `ShardIterator` 方法 (上方) 測試回合的 `GET /streams/{stream-name}/sharditerator` 值，然後選擇**測試**。

    成功回應承載與下列輸出類似：

   ```
   {
     "MillisBehindLatest": 0,
     "NextShardIterator": "AAAAAAAAAAF...",
     "Records": [ ... ]
   }
   ```