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

# GStreamer 元素參數參考
<a name="examples-gstreamer-plugin-parameters"></a>

若要將影片傳送至 Amazon Kinesis Video Streams 生產者 C\$1\$1 SDK，您可以將 指定`kvssink`為管道的*目的地*或最終目的地。此參考提供有關必要的 `kvssink` 和選用參數的資訊。如需詳細資訊，請參閱[範例：Kinesis Video Streams 生產者 SDK GStreamer 外掛程式 - kvssink](examples-gstreamer-plugin.md)。

**主題**
+ [提供登入資料給 `kvssink`](#credentials-to-kvssink)
+ [提供區域給 `kvssink`](#kvssink-region)
+ [`kvssink` 選用參數](#kvssink-optional-parameters)

## 提供登入資料給 `kvssink`
<a name="credentials-to-kvssink"></a>

若要允許 `kvssink` GStreamer 元素向 發出請求 AWS，請在呼叫 Amazon Kinesis Video Streams 服務時提供 AWS 登入資料以供其使用。登入資料提供者鏈結會依下列順序尋找登入資料：

### 1. AWS IoT 憑證
<a name="collapsible-section-1"></a>

若要設定 AWS IoT 登入資料，請參閱 [使用 控制對 Kinesis Video Streams 資源的存取 AWS IoT](how-iot.md)。

`iot-credentials` 參數值必須以 開頭`iot-certificate,`，後面接著下列 *key*=*value* 對的逗號分隔清單。


****  

| 金錀 | 必要 | 描述 | 
| --- | --- | --- | 
| ca-path | 是 | 用於透過 TLS 與後端服務建立信任的 CA 憑證檔案路徑。 

**Example**  
**範例**：` /file/path/to/certificate.pem` | 
| cert-path | 是 | X.509 憑證的檔案路徑。 

**Example**  
**範例**：`/file/path/to/certificateID-certificate.pem.crt` | 
| endpoint | 是 | 您 AWS 帳戶的 AWS IoT Core 登入資料端點提供者端點。請參閱 [AWS IoT 開發人員指南](https://docs.aws.amazon.com//iot/latest/developerguide/authorizing-direct-aws.html)。 

**Example**  
**範例**：`credential-account-specific-prefix.credentials.iot.aws-region.amazonaws.com` | 
| key-path | 是 | 公有/私有金鑰對中使用的私有金鑰的檔案路徑。 

**Example**  
**範例**：`/file/path/to/certificateID-private.pem.key` | 
| role-aliases | 是 | 連線到 時，指向要使用之 AWS IAM 角色的角色別名名稱 AWS IoT Core。 

**Example**  
**範例**：`KvsCameraIoTRoleAlias` | 
| iot-thing-name | 否 | `iot-thing-name` 為選用。如果`iot-thing-name`未提供 ，則會使用 `stream-name` 參數值。 

**Example**  
**範例**：`kvs_example_camera` | 

**Example**  
**範例**：  

```
gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" iot-certificate="iot-certificate,endpoint=credential-account-specific-prefix.credentials.iot.aws-region.amazonaws.com,cert-path=certificateID-certificate.pem.crt,key-path=certificateID-private.pem.key,ca-path=certificate.pem,role-aliases=YourRoleAlias,iot-thing-name=YourThingName"
```

### 2. 環境變數
<a name="collapsible-section-2"></a>

若要讓 `kvssink`使用環境中的登入資料，請設定下列環境變數：


****  

| 環境變數名稱 | 必要 | 描述 | 
| --- | --- | --- | 
| AWS\$1ACCESS\$1KEY\$1ID | 是 | 用來存取 Amazon Kinesis Video Streams 的 AWS 存取金鑰。 | 
| AWS\$1SECRET\$1ACCESS\$1KEY | 是 | 與存取金鑰相關聯的 AWS 私密金鑰。 | 
| AWS\$1SESSION\$1TOKEN | 否 | 如果您直接從 AWS STS 操作使用臨時安全登入資料，請指定所需的工作階段字符值。 | 

設定環境變數會變更使用的數值，直到 Shell 工作階段結束或直到您將該變數設為其他數值。若要讓變數在未來的工作階段中持續存在，請在 shell 的啟動指令碼中設定它們。

### 3. `access-key`、 `secret-key` 參數
<a name="collapsible-section-3"></a>

若要直接指定登入資料做為`kvssink`參數，請設定下列參數：


****  

| `kvssink` 參數名稱 | 必要 | 描述 | 
| --- | --- | --- | 
| access-key | 是 | 用來存取 Amazon Kinesis Video Streams 的 AWS 存取金鑰。 | 
| secret-key | 是 | 與存取金鑰相關聯的 AWS 私密金鑰。 | 
| session-token | 否 | 如果您直接從 AWS STS 操作使用臨時安全登入資料，請指定所需的工作階段字符值。 | 

**Example**  
**使用靜態登入資料：**  

```
gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" access-key="AKIDEXAMPLE" secret-key="SKEXAMPLE"
```

**Example**  
**使用臨時登入資料：**  

```
gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" access-key="AKIDEXAMPLE" secret-key="SKEXAMPLE" session-token="STEXAMPLE"
```

### 4. 登入資料檔案
<a name="collapsible-section-4"></a>

**重要**  
如果您已選取上述其中一種方法，則無法使用 `credential-path` `kvssink` 參數。


****  

| `kvssink` 參數名稱 | 必要 | 描述 | 
| --- | --- | --- | 
| credential-path | 是 | 文字檔案的路徑，其中包含特定格式的登入資料。 | 

文字檔案必須包含下列其中一種格式的登入資料：
+ CREDENTIALS *YourAccessKey* *YourSecretKey*
+ CREDENTIALS *YourAccessKey* *過期* *YourSecretKey* *SessionToken*

**Example**  
**範例：**您的`credentials.txt`檔案位於 `/home/ubuntu`並包含下列項目：  
`CREDENTIALS AKIDEXAMPLE 2023-08-10T22:43:00Z SKEXAMPLE STEXAMPLE`  
若要在 中使用它`kvssink`，請輸入：  

```
gst-launch-1.0 -v ... ! kvssink stream-name="YourStream" aws-region="YourRegion" credential-path="/home/ubuntu/credentials.txt" 
```
過期時間應該至少為 5 \$1 30 \$1 3 = 未來 **38** 秒。寬限期在 中定義為 `IOT_CREDENTIAL_FETCH_GRACE_PERIOD`變數[https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/Common/IotCredentialProvider.h](https://github.com/awslabs/amazon-kinesis-video-streams-producer-c/blob/master/src/source/Common/IotCredentialProvider.h)。如果登入資料在您啟動 時太接近過期`kvssink`，您會收到錯誤碼 `0x52000049 - STATUS_INVALID_TOKEN_EXPIRATION`。
`kvssink` 不會修改登入資料檔案。如果您使用的是暫時登入資料，則必須在過期時間減去寬限期之前，由外部來源更新登入資料檔案。

## 提供區域給 `kvssink`
<a name="kvssink-region"></a>

以下是區域查詢順序：

1. `AWS_DEFAULT_REGION` 環境變數會先檢閱。如果已設定，則會使用該區域來設定用戶端。

1. `aws-region` 接下來會檢閱 參數。如果已設定，則會使用該區域來設定用戶端。

1. 如果之前的方法都未使用，則 `kvssink`預設為 `us-west-2`。

## `kvssink` 選用參數
<a name="kvssink-optional-parameters"></a>

`kvssink` 元素具有下列選用參數：如需這些參數的相關資訊，請參閱 [Kinesis 影片串流結構](producer-reference-structures-stream.md)。


****  

| 參數 | Description | 單位/類型 | 預設 | 
| --- | --- | --- | --- | 
| stream-name  | 目的地 Amazon Kinesis 視訊串流的名稱。 如果未指定串流名稱，將使用預設串流名稱：「DEFAULT\$1STREAM」。如果具有該預設名稱的串流尚不存在，則會建立該串流。  |  |  | 
| absolute-fragment-times | 是否使用絕對片段時間。 | Boolean | true | 
| access-key | 用來存取 Kinesis Video Streams 的 AWS 存取金鑰。 您必須設定 AWS 登入資料或提供此參數。若要提供此資訊，請輸入下列內容： <pre>export AWS_ACCESS_KEY_ID=</pre> |  |  | 
| avg-bandwidth-bps | 串流的預期平均頻寬。 | 每秒位元數 | 4194304 | 
| aws-region |  AWS 區域 要使用的 。  您也可以為區域提供 `AWS_DEFAULT_REGION`環境變數。如果同時設定環境變數和 kvssink 參數，則環境變數優先。   `us-west-2` 如果未另外指定，則區域預設為 。   | String | "us-west-2" | 
| buffer-duration | 串流緩衝持續時間。 | 秒鐘 | 120 | 
| codec-id | 串流的編解碼器 ID。 | String | "V\$1MPEG4/ISO/AVC" | 
| connection-staleness | 之後呼叫串流過時回呼的時間。 | 秒鐘 | 60 | 
| content-type | 串流的內容類型。 | String | "video/h264" | 
| fragment-acks | 發生錯誤時欲採取的動作。 | Boolean | true | 
| fragment-duration | 您需要的片段持續時間。 | 毫秒 | 2000 | 
| framerate | 預期的影格率。 | 每秒影格 | 25 | 
| frame-timecodes | 是否使用影格時間碼或者使用目前時間回呼產生時間戳記。 | Boolean | true | 
| key-frame-fragmentation | 是否在關鍵影格上產生片段。 | Boolean | true | 
| log-config | 日誌設定路徑。 | String | "../kvs\$1log\$1configuration" | 
| max-latency | 串流的最大延遲。 | 秒鐘 | 60 | 
| recalculate-metrics | 是否重新計算指標。 | Boolean | true | 
| replay-duration | 若發生錯誤啟用重新啟動時，則向後捲動目前閱讀器以重放的持續時間。 | 秒鐘 | 40 | 
| restart-on-error | 是否發生錯誤時重新啟動。 | Boolean | true | 
| retention-period | 串流是保留所需的時間。 | 小時 | 2 | 
| rotation-period | 金鑰輪換期間。如需詳細資訊，請參閱[輪換 AWS KMS 金鑰](https://docs.aws.amazon.com/kms/latest/developerguide/rotate-keys.html)。 | 秒鐘 | 3600 | 
| secret-key |  用來存取 Kinesis Video Streams 的 AWS 私密金鑰。 您必須設定 AWS 登入資料或提供此參數。 <pre>export AWS_SECRET_ACCESS_KEY=</pre>  |  |  | 
| session-token | 如果您直接從 AWS STS 操作使用臨時安全登入資料，請指定所需的工作階段字符值。 |  |  | 
| storage-size | 以 MB (MiB) 為單位的裝置儲存體大小。如需設定裝置儲存的詳細資訊，請參閱[StorageInfo](producer-reference-structures-producer.md#producer-reference-structures-producer-storageinfo)。 | Mebibyte (MiB) | 128 | 
| streaming-type | 串流類型。有效值包含：[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/kinesisvideostreams/latest/dg/examples-gstreamer-plugin-parameters.html) | 列舉 GstKvsSinkStreamingType | 0：即時 | 
| timecode-scale | MKV 時間碼比例。 | 毫秒 | 1 | 
| track-name | MKV 音軌名稱。 | String | "kinesis\$1video" | 
| iot-certificate | AWS IoT 要在 `kvssink`元素中使用的登入資料。 `iot-certificate` 接受下列金鑰和值：  `iot-thing-name` 是**選用**的。如果`iot-thing-name`未提供 ，則會使用 `stream-name` 參數值。  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/kinesisvideostreams/latest/dg/examples-gstreamer-plugin-parameters.html) | String | 無 |