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

# 範例：使用 PutMedia API 將資料傳送至 Kinesis Video Streams
<a name="examples-putmedia"></a>

本範例示範如何使用 [PutMedia](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_PutMedia.html) API。它說明如何傳送已採用容器格式 (MKV) 的資料。如果您的資料必須在傳送之前組合成容器格式 （例如，如果您要將攝影機視訊資料組合成影格），請參閱 [上傳至 Kinesis Video Streams](producer-sdk.md)。

**注意**  
`PutMedia` 此操作僅適用於 C\$1\$1 和 Java SDKs。這是因為連線、資料流程和確認的全雙工管理。其他語言不支援此功能。

**Topics**
+ [下載並設定程式碼](#examples-putmedia-download)
+ [撰寫並檢查程式碼](#examples-putmedia-write)
+ [執行並驗證程式碼](#examples-putmedia-run)

## 下載並設定程式碼
<a name="examples-putmedia-download"></a>

依照步驟下載 Java 範例程式碼、將專案匯入您的 Java IDE、設定程式庫位置，以及設定程式碼以使用您的登入資料 AWS 。

1. 建立目錄，由 GitHub 儲存庫複製範例原始碼。`PutMedia` 範例為 [Java](producer-sdk-javaapi.md) 的一部分。

   ```
   git clone https://github.com/awslabs/amazon-kinesis-video-streams-producer-sdk-java
   ```

1. 開啟您正在使用的 Java IDE （例如 [Eclipse](https://www.eclipse.org/) 或 [IntelliJ IDEA](https://www.jetbrains.com/idea/))，並匯入您下載的 Apache Maven 專案：
   + **在 Eclipse 中：**請選擇 **File (檔案)**、**Import (匯入)**、**Maven**、**Existing Maven Projects (現有 Maven 專案)**，並巡覽至下載套件的根目錄。選取 `pom.xml` 檔案。
   + **在 IntelliJ Idea：**選擇 **Import (匯入)**。巡覽至已下載套件根目錄的 `pom.xml` 檔案。

    如需更多詳細資訊，請參閱 IDE 文件。

1. 請更新專案，讓 IDE 能夠找到您匯入的程式庫。
   + 對於 IntelliJ IDEA 請執行下列步驟：

     1. 開啟專案 **lib** 目錄的內容 (按一下右鍵) 功能表，然後選擇 **Add as library (新增為程式庫)**。

     1. 選擇**檔案**，然後選擇**專案結構**。

     1. 請在 **Project Settings (專案詳細資訊)** 下選擇 **Modules (模組)**。

     1. 請在 **Sources (來源)** 標籤將 **Language Level (語言層級)** 設定為 **7** 或以上。
   + 對於 Eclipse 請執行下列步驟：

     1. 開啟專案的內容 (按一下右鍵) 功能表，然後選擇 **Properties (屬性)**、**Java Build Path (Java 建置路徑)**、**Source (來源)**。然後執行下列動作：

        1. 請在 **Source (來源)** 標籤按兩下 **Native library location (原生程式庫位置)**。

        1. 請在 **Native Library Folder Configuration (原生程式庫資料夾設定)** 精靈之中選擇 **Workspace (工作空間)**。

        1. 請在 **Native Library Folder (原生程式庫資料夾)** 選項之中選擇專案的 **lib** 目錄。

     1. 開啟專案的內容 (按一下右鍵) 功能表，然後選擇 **Properties (屬性)**。然後執行下列動作：

        1. 請在 **Libraries (程式庫)** 標籤選擇 **Add Jars (新增 Jar)**。

        1. 請在 **JAR selection (JAR 選擇)** 精靈之中選擇專案 `lib` 目錄之中的所有 .jar。

## 撰寫並檢查程式碼
<a name="examples-putmedia-write"></a>

`PutMedia` API 範例 (`PutMediaDemo`) 顯示下列編碼模式：

**Topics**
+ [建立 PutMediaClient](#producersdk-javaapi-writecode-putmediaapi-putmediaclient)
+ [串流媒體並暫停執行緒](#producersdk-javaapi-writecode-putmediaapi-run)

本節程式碼範例來自 `PutMediaDemo` 類別。

### 建立 PutMediaClient
<a name="producersdk-javaapi-writecode-putmediaapi-putmediaclient"></a>

建立 `PutMediaClient` 物件需要下列參數：
+ `PutMedia` 端點的 URI。
+ `InputStream` 指向 MKV 檔案進行串流。
+ 串流名稱。本範例使用 [使用 Java 生產者程式庫](producer-sdk-javaapi.md) (`my-stream`) 建立的串流。如欲使用不同串流，請變更下列參數：

  ```
  private static final String STREAM_NAME="my-stream";
  ```
**注意**  
`PutMedia` API 範例不會建立串流。您必須使用 的測試應用程式[使用 Java 生產者程式庫](producer-sdk-javaapi.md)、Kinesis Video Streams 主控台或 來建立串流 AWS CLI。
+ 目前的時間戳記。
+ 時間編碼類型。範例使用 `RELATIVE`，顯示時間戳記與容器開始有關。
+ `AWSKinesisVideoV4Signer` 物件驗證收到的封包是由獲得授權的寄件者傳送。
+ 以 Kbps 為單位的最大上游頻寬。
+ `AckConsumer` 物件接收封包收到的確認。

下列程式碼建立 `PutMediaClient` 物件：

```
/* actually URI to send PutMedia request */
final URI uri = URI.create(KINESIS_VIDEO_DATA_ENDPOINT + PUT_MEDIA_API);

/* input stream for sample MKV file */
final InputStream inputStream = new FileInputStream(MKV_FILE_PATH);

/* use a latch for main thread to wait for response to complete */
final CountDownLatch latch = new CountDownLatch(1);

/* a consumer for PutMedia ACK events */
final AckConsumer ackConsumer = new AckConsumer(latch);

/* client configuration used for AWS SigV4 signer */
final ClientConfiguration configuration = getClientConfiguration(uri);

/* PutMedia client */
final PutMediaClient client = PutMediaClient.builder()
        .putMediaDestinationUri(uri)
        .mkvStream(inputStream)
        .streamName(STREAM_NAME)
        .timestamp(System.currentTimeMillis())
        .fragmentTimeCodeType("RELATIVE")
        .signWith(getKinesisVideoSigner(configuration))
        .upstreamKbps(MAX_BANDWIDTH_KBPS)
        .receiveAcks(ackConsumer)
        .build();
```

### 串流媒體並暫停執行緒
<a name="producersdk-javaapi-writecode-putmediaapi-run"></a>

建立用戶端之後，範例開始與 `putMediaInBackground` 進行非同步串流。主要執行緒將由 `latch.await` 暫停直到 `AckConsumer` 傳回為止，屆時用戶端將會關閉。

```
 /* start streaming video in a background thread */
            client.putMediaInBackground();

            /* wait for request/response to complete */
            latch.await();

            /* close the client */
            client.close();
```

## 執行並驗證程式碼
<a name="examples-putmedia-run"></a>

如欲執行 `PutMedia` API 範例，請執行下列步驟：

1. 在 Kinesis Video Streams 主控台`my-stream`或使用 建立名為 的串流 AWS CLI。

1. 將工作目錄變更為 Java 製作者開發套件目錄：

   ```
   cd /<YOUR_FOLDER_PATH_WHERE_SDK_IS_DOWNLOADED>/amazon-kinesis-video-streams-producer-sdk-java/
   ```

1. 編譯 Java 開發套件和示範應用程式：

   ```
   mvn package
   ```

1. 在目錄中建立一個 `/tmp` 暫時的檔案名稱：

   ```
   jar_files=$(mktemp)
   ```

1. 建立從本機儲存庫 classpath 有相依性字串的檔案：

   ```
   mvn -Dmdep.outputFile=$jar_files dependency:build-classpath
   ```

1. 設定 `LD_LIBRARY_PATH` 環境變數的值如下：

   ```
   export LD_LIBRARY_PATH=/<YOUR_FOLDER_PATH_WHERE_SDK_IS_DOWNLOADED>/amazon-kinesis-video-streams-producer-sdk-cpp/kinesis-video-native-build/downloads/local/lib:$LD_LIBRARY_PATH
   $ classpath_values=$(cat $jar_files)
   ```

1. 從命令列執行示範，如下所示，並提供您的 AWS 登入資料：

   ```
   java -classpath target/kinesisvideo-java-demo-1.0-SNAPSHOT.jar:$classpath_values -Daws.accessKeyId=${ACCESS_KEY} -Daws.secretKey=${SECRET_KEY} -Djava.library.path=/opt/amazon-kinesis-video-streams-producer-sdk-cpp/kinesis-video-native-build com.amazonaws.kinesisvideo.demoapp.DemoAppMain
   ```

1. 開啟 [Kinesis Video Streams 主控台](https://console.aws.amazon.com//kinesisvideo/home/)，然後在**管理串流**頁面上選擇您的串流。影片於 **Video Preview (影片預覽)** 窗格播放。