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

# 使用 AWS CLI 執行 Amazon Kinesis Data Streams 操作
<a name="getting-started"></a>

本節說明如何使用 執行基本 Amazon Kinesis Data Streams 操作 AWS Command Line Interface。您將了解 Kinesis Data Streams 資料流程的基礎原理，以及將資料放入 Kinesis 資料串流和從中取得資料的必要步驟。

 如果您是 Kinesis Data Streams 的新手，請先熟悉一下 [Amazon Kinesis Data Streams 術語和概念](key-concepts.md) 中所介紹的概念和術語。

**Topics**
+ [教學課程：安裝和設定 Kinesis Data Streams AWS CLI 的](kinesis-tutorial-cli-installation.md)
+ [教學課程：使用 執行基本 Kinesis Data Streams 操作 AWS CLI](fundamental-stream.md)

對於 CLI 存取，您需要存取金鑰 ID 和私密存取金鑰。盡可能使用臨時憑證，而不是長期存取金鑰。臨時憑證包含存取金鑰 ID、私密存取金鑰，以及指出憑證何時到期的安全符記。如需詳細資訊，請參閱《*IAM 使用者指南*》中的[將臨時登入資料與 AWS 資源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html)搭配使用。

您可在[建立 IAM 使用者](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/get-set-up-for-amazon-ec2.html#create-an-iam-user)中找到 IAM 和安全金鑰設定的詳細逐步說明。

本節中討論到的特定命令將一字不差地提供，但其每次執行時具體的數值必然會有所不同。此外，雖然範例使用 美國西部 (奧勒岡) 區域，但本節中的步驟在[支援 Kinesis Data Streams 的任一區域](https://docs.aws.amazon.com/general/latest/gr/rande.html#ak_region)中都適用。

# 教學課程：安裝和設定 Kinesis Data Streams AWS CLI 的
<a name="kinesis-tutorial-cli-installation"></a>

## 安裝 AWS CLI
<a name="install-cli"></a>

如需如何為 Windows AWS CLI 和 Linux、OS X 和 Unix 作業系統安裝 的詳細步驟，請參閱[安裝 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html)。

 使用以下命令列出可用的選項和服務：

```
aws help
```

您將使用 Kinesis Data Streams 服務，因此您可以使用下列命令檢閱與 Kinesis Data Streams 相關的 AWS CLI 子命令：

```
aws kinesis help
```

該命令產生的輸出將包括可用的 Kinesis Data Streams 命令：

```
AVAILABLE COMMANDS

       o add-tags-to-stream

       o create-stream

       o delete-stream

       o describe-stream

       o get-records

       o get-shard-iterator

       o help

       o list-streams

       o list-tags-for-stream

       o merge-shards

       o put-record

       o put-records

       o remove-tags-from-stream

       o split-shard

       o wait
```

 上述命令清單與[《Amazon Kinesis 服務 API 參考》](https://docs.aws.amazon.com/kinesis/latest/APIReference/)所記載的 Kinesis Data Streams API 相對應。例如，`create-stream` 命令對應至 `CreateStream` API 動作。

 現在 AWS CLI 已成功安裝 ，但未設定。請繼續閱讀下一節的說明。

## 設定 AWS CLI
<a name="config-cli"></a>

 對於一般用途， `aws configure`命令是設定 AWS CLI 安裝的最快方式。如需詳細資訊，請參閱[設定 AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html)。

# 教學課程：使用 執行基本 Kinesis Data Streams 操作 AWS CLI
<a name="fundamental-stream"></a>

本節說明如何使用 AWS CLI透過命令列對 Kinesis 資料串流執行基本操作。請您務必先熟悉 [Amazon Kinesis Data Streams 術語和概念](key-concepts.md) 所討論的概念。

**注意**  
建立串流之後，您的帳戶會產生 Kinesis Data Streams 用量的名目費用，因為 Kinesis Data Streams 不符合 AWS 免費方案的資格。完成本教學課程後，請刪除您的 AWS 資源以停止產生費用。如需詳細資訊，請參閱[步驟 4：清理](#clean-up)。

**Topics**
+ [步驟 1：建立串流](#create-stream)
+ [步驟 2：放置記錄](#put-record)
+ [步驟 3：取得記錄](#get-records)
+ [步驟 4：清理](#clean-up)

## 步驟 1：建立串流
<a name="create-stream"></a>

 您的第一個步驟是建立串流並確認其是否已成功建立。使用以下命令建立名為 "Foo" 的串流：

```
aws kinesis create-stream --stream-name Foo
```

接著，發出以下命令檢查串流的建立進度：

```
aws kinesis describe-stream-summary --stream-name Foo
```

您應會看到類似如下範例的輸出：

```
{
    "StreamDescriptionSummary": {
        "StreamName": "Foo",
        "StreamARN": "arn:aws:kinesis:us-west-2:123456789012:stream/Foo",
        "StreamStatus": "CREATING",
        "RetentionPeriodHours": 48,
        "StreamCreationTimestamp": 1572297168.0,
        "EnhancedMonitoring": [
            {
                "ShardLevelMetrics": []
            }
        ],
        "EncryptionType": "NONE",
        "OpenShardCount": 3,
        "ConsumerCount": 0
    }
}
```

 在此範例中，串流具有狀態 CREATING，這表示尚未準備好使用。請於幾分鐘後再次檢查，屆時您應會看到類似如下範例的輸出：

```
{
    "StreamDescriptionSummary": {
        "StreamName": "Foo",
        "StreamARN": "arn:aws:kinesis:us-west-2:123456789012:stream/Foo",
        "StreamStatus": "ACTIVE",
        "RetentionPeriodHours": 48,
        "StreamCreationTimestamp": 1572297168.0,
        "EnhancedMonitoring": [
            {
                "ShardLevelMetrics": []
            }
        ],
        "EncryptionType": "NONE",
        "OpenShardCount": 3,
        "ConsumerCount": 0
    }
}
```

此輸出中有您不需要在本教學課程中的資訊。現在的重要資訊是 `"StreamStatus": "ACTIVE"`，它會告訴您串流已準備好可供使用，以及您請求的單一碎片上的資訊。您也可以使用 `list-streams` 命令確認新串流是否存在，如下所示：

```
aws kinesis list-streams
```

輸出：

```
{
    "StreamNames": [
        "Foo"
    ]
}
```

## 步驟 2：放置記錄
<a name="put-record"></a>

 現在您已有了作用中的串流，即可準備開始放入一些資料。本教學課程使用最簡單可行的 `put-record` 命令，將包含文字 "testdata" 的單一資料記錄放入串流：

```
aws kinesis put-record --stream-name Foo --partition-key 123 --data testdata
```

 此命令若成功，將產生類似如下範例的輸出：

```
{
    "ShardId": "shardId-000000000000",
    "SequenceNumber": "49546986683135544286507457936321625675700192471156785154"
}
```

恭喜，您剛已順利加入資料至串流！接下來您將了解如何從串流取出資料。

## 步驟 3：取得記錄
<a name="get-records"></a>

**GetShardIterator**

 您必須先取得您感興趣的碎片的碎片反覆運算器，才能從串流取得資料。碎片疊代運算代表了消費者 (本例中為 `get-record` 命令) 將從中讀取資料的串流及碎片的位置。您將使用 `get-shard-iterator`命令，如下所示：

```
aws kinesis get-shard-iterator --shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON --stream-name Foo
```

如前所述，`aws kinesis` 命令與 Kinesis Data Streams API 相對應，所以如果您對任何顯示的參數感興趣，均可閱讀 [https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetShardIterator.html) API 參考主題以詳加了解。成功執行將產生類似下列範例的輸出：

```
{
    "ShardIterator": "AAAAAAAAAAHSywljv0zEgPX4NyKdZ5wryMzP9yALs8NeKbUjp1IxtZs1Sp+KEd9I6AJ9ZG4lNR1EMi+9Md/nHvtLyxpfhEzYvkTZ4D9DQVz/mBYWRO6OTZRKnW9gd+efGN2aHFdkH1rJl4BL9Wyrk+ghYG22D2T1Da2EyNSH1+LAbK33gQweTJADBdyMwlo5r6PqcP2dzhg="
}
```

一長串看似隨機字元的字串就是碎片疊代運算 (您的字串會有所出入)。您必須將碎片疊代運算複製/貼上至 get 命令，如下所示。碎片疊代運算的有效期為 300 秒，這段時間應足夠讓您將碎片疊代運算複製/貼入下一個命令中。在貼上至下一個命令之前，您必須從碎片疊代運算中移除任何新行。如果您收到錯誤訊息，指出碎片疊代運算不再有效，請再次執行 `get-shard-iterator`命令。

**GetRecords**

`get-records` 命令會從串流取得資料，並將解析成 Kinesis Data Streams API 的 [https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html) 呼叫。碎片迭代運算指定了碎片中您希望開始循序讀取資料記錄的位置。如果疊代運算所指向的碎片部分沒有可用的記錄，`GetRecords` 將傳回空白清單。可能需要多次呼叫才能到達包含記錄的部分碎片。

在下列 `get-records`命令範例中：

```
aws kinesis get-records --shard-iterator AAAAAAAAAAHSywljv0zEgPX4NyKdZ5wryMzP9yALs8NeKbUjp1IxtZs1Sp+KEd9I6AJ9ZG4lNR1EMi+9Md/nHvtLyxpfhEzYvkTZ4D9DQVz/mBYWRO6OTZRKnW9gd+efGN2aHFdkH1rJl4BL9Wyrk+ghYG22D2T1Da2EyNSH1+LAbK33gQweTJADBdyMwlo5r6PqcP2dzhg=
```

 如果您是從像是 bash 的 Unix 類型命令處理器執行本教學課程，您可以使用巢狀命令自動取得碎片迭代器，如下所示：

```
SHARD_ITERATOR=$(aws kinesis get-shard-iterator --shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON --stream-name Foo --query 'ShardIterator')

aws kinesis get-records --shard-iterator $SHARD_ITERATOR
```

如果您是從支援 PowerShell 的系統執行本教學課程，您可以使用下列命令自動取得碎片迭代器：

```
aws kinesis get-records --shard-iterator ((aws kinesis get-shard-iterator --shard-id shardId-000000000000 --shard-iterator-type TRIM_HORIZON --stream-name Foo).split('"')[4])
```

`get-records` 命令的成功結果會從串流請求您在取得碎片迭代器時所指定碎片的記錄，如下列範例所示：

```
{
  "Records":[ {
    "Data":"dGVzdGRhdGE=",
    "PartitionKey":"123”,
    "ApproximateArrivalTimestamp": 1.441215410867E9,
    "SequenceNumber":"49544985256907370027570885864065577703022652638596431874"
  } ],
  "MillisBehindLatest":24000,
  "NextShardIterator":"AAAAAAAAAAEDOW3ugseWPE4503kqN1yN1UaodY8unE0sYslMUmC6lX9hlig5+t4RtZM0/tALfiI4QGjunVgJvQsjxjh2aLyxaAaPr+LaoENQ7eVs4EdYXgKyThTZGPcca2fVXYJWL3yafv9dsDwsYVedI66dbMZFC8rPMWc797zxQkv4pSKvPOZvrUIudb8UkH3VMzx58Is="
}
```

請注意， `get-records`如上所述為 *請求*，這表示即使串流中有記錄，您也可能收到零筆或多筆記錄。傳回的任何記錄可能不會代表目前串流中的所有記錄。這是正常的，生產程式碼會以適當的間隔輪詢串流以取得記錄。此輪詢速度會根據您的特定應用程式設計需求而有所不同。

在教學課程的這個部分中，您會注意到資料似乎是垃圾，這不是`testdata`我們傳送的純文字。這是因為 `put-record` 採用 Base64 編碼方式，讓您能夠傳送二進位資料。不過， 中的 Kinesis Data Streams 支援 AWS CLI 不提供 Base64 *解碼*，因為 Base64 解碼為列印到 stdout 的原始二進位內容可能會導致某些平台和終端機上不必要的行為和潛在的安全問題。若您使用 Base64 解碼器 (如 [https://www.base64decode.org/](https://www.base64decode.org/)) 手動解碼 `dGVzdGRhdGE=`，就會看到實際原文是 `testdata`。就本教學課程而言，這就已足夠，因為實際上， AWS CLI 很少用於使用資料。通常，它會用來監控串流的狀態並取得資訊，如先前所示 (`describe-stream` 和 `list-streams`)。如需有關 KCL 的詳細資訊，請參閱[使用 KCL 開發具有共用輸送量的自訂取用者](https://docs.aws.amazon.com/streams/latest/dev/shared-throughput-kcl-consumers.html)。

`get-records` 不一定會傳回指定串流/碎片中的所有記錄。若發生這種情況，請由最近的結果使用 `NextShardIterator` 以取得下一組記錄。如果有更多資料放入串流，這是生產應用程式中的正常情況，您可以`get-records`在每次使用 持續輪詢資料。不過，如果您未在 300 秒的碎片疊代運算生命週期內`get-records`使用下一個碎片疊代運算呼叫 ，您會收到錯誤訊息，而且必須使用 `get-shard-iterator`命令來取得新的碎片疊代運算。

上述輸出中還提供了 `MillisBehindLatest`，這是從串流的頂端回應 [GetRecords](https://docs.aws.amazon.com/kinesis/latest/APIReference/API_GetRecords.html) 操作的毫秒數，表示取用者落後目前時間有多久。值為零表示記錄處理已跟上進度，此時沒有任何新記錄可供處理。在本教學課程中，若您一邊閱讀內容一邊操作，可能會看到這個數值相當大。根據預設，資料記錄會保留在串流中 24 小時，等待您擷取。此時間範圍稱為保留期間，最長可設定成 365 天。

`NextShardIterator` 即使串流中目前沒有更多記錄，成功`get-records`結果一律會有 。這是假定生產者可能在任何特定時間內將更多記錄放入串流的一種輪詢模式。您儘管可自行撰寫輪詢常式，但若您使用前述的 KCL 開發消費者應用程式，該程式庫將會為您處理妥輪詢事宜。

如果您在串流和碎片中沒有更多記錄`get-records`之前呼叫 ，您會看到具有類似下列範例之空白記錄的輸出：

```
{
    "Records": [],
    "NextShardIterator": "AAAAAAAAAAGCJ5jzQNjmdhO6B/YDIDE56jmZmrmMA/r1WjoHXC/kPJXc1rckt3TFL55dENfe5meNgdkyCRpUPGzJpMgYHaJ53C3nCAjQ6s7ZupjXeJGoUFs5oCuFwhP+Wul/EhyNeSs5DYXLSSC5XCapmCAYGFjYER69QSdQjxMmBPE/hiybFDi5qtkT6/PsZNz6kFoqtDk="
}
```

## 步驟 4：清理
<a name="clean-up"></a>

刪除您的串流以釋出資源，並避免您的帳戶產生意外費用。每當您建立串流且不會使用它時，請執行此操作，因為無論您是否使用它來放置和取得資料，每個串流都會產生費用。清除命令如下所示：

```
aws kinesis delete-stream --stream-name Foo
```

 成功不會產生輸出。使用 `describe-stream`檢查刪除進度：

```
aws kinesis describe-stream-summary --stream-name Foo
```

 如果您在刪除命令之後立即執行此命令，您會看到類似下列範例的輸出：

```
{
    "StreamDescriptionSummary": {
        "StreamName": "samplestream",
        "StreamARN": "arn:aws:kinesis:us-west-2:123456789012:stream/samplestream",
        "StreamStatus": "ACTIVE",
```

 串流完全刪除後，`describe-stream` 將導致「找不到」的錯誤。

```
A client error (ResourceNotFoundException) occurred when calling the DescribeStreamSummary operation: 
Stream Foo under account 123456789012 not found.
```