建立及管理 DVR 工作階段

本頁說明如何建立及管理 Live Stream API 數位錄影機 (DVR) 工作階段。DVR 工作階段是頻道的子資源。你可以使用 DVR 工作階段錄製未來的直播內容。詳情請參閱建立 DVR 工作階段這份指南。

設定 Google Cloud 專案和驗證

如果您尚未建立 Google Cloud 專案和憑證，請參閱「開始前」一節。

事前準備

您必須先建立下列資源，才能建立 DVR 工作階段：

1. 建立輸入端點

2. 使用留存設定和資訊清單鍵建立管道

建立 DVR 工作階段

如要建立 DVR 工作階段，請使用 projects.locations.channels.dvrSessions.create 方法。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_NUMBER：您的 Google Cloud 專案編號，位於 IAM 設定頁面上的「專案編號」欄位
• LOCATION：頻道所在位置；請使用支援的區域之一
  顯示地區
  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • us-west2
  • northamerica-northeast1
  • southamerica-east1
  • asia-east1
  • asia-east2
  • asia-south1
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1
  • europe-north1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
• CHANNEL_ID：管道的使用者定義 ID
• DVR_SESSION_ID：DVR 工作階段的使用者定義 ID
• INTERVAL_START_TIME：原始直播資訊清單中的 Unix Epoch 紀元時間；使用 RFC3339 世界標準時間「Zulu」格式的時間戳記 (例如 2014-10-02T15:01:23Z)
• INTERVAL_END_TIME：原始直播資訊清單中的 Mark-out Unix Epoch 時間；使用 RFC3339 世界標準時間「Zulu」格式的時間戳記 (例如 2014-10-02T15:01:23Z)

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意：以下指令假設您已使用使用者帳戶登入 gcloud CLI，方法是執行 gcloud init 或 gcloud auth login，或是使用 Cloud Shell，後者會自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，即可在目前目錄中建立或覆寫此檔案：

cat > request.json << 'EOF'
{
  "dvrManifests":[
    {
      "manifestKey": "manifest_hls"
    }
  ],
  "dvrWindows":[
    {
      "timeInterval": {
        "startTime": "INTERVAL_START_TIME",
        "endTime": "INTERVAL_END_TIME"
      }
    }
  ]
}
EOF

接著，執行下列指令來傳送 REST 要求：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions?dvr_session_id=DVR_SESSION_ID"

PowerShell (Windows)

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，即可在目前目錄中建立或覆寫此檔案：

@'
{
  "dvrManifests":[
    {
      "manifestKey": "manifest_hls"
    }
  ],
  "dvrWindows":[
    {
      "timeInterval": {
        "startTime": "INTERVAL_START_TIME",
        "endTime": "INTERVAL_END_TIME"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions?dvr_session_id=DVR_SESSION_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

這個指令會建立長期執行作業 (LRO)，您可以使用該作業追蹤要求的進度。詳情請參閱「管理長時間執行的作業 」。

取得 DVR 工作階段詳細資料

如要取得 DVR 工作階段的詳細資料，請使用 projects.locations.channels.dvrSessions.get 方法。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_NUMBER：您的 Google Cloud 專案編號，位於 IAM 設定頁面上的「專案編號」欄位
• LOCATION：頻道所在位置；請使用支援的區域之一
  顯示地區
  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • us-west2
  • northamerica-northeast1
  • southamerica-east1
  • asia-east1
  • asia-east2
  • asia-south1
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1
  • europe-north1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
• CHANNEL_ID：管道的使用者定義 ID
• DVR_SESSION_ID：DVR 工作階段的使用者定義 ID

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意：以下指令假設您已使用使用者帳戶登入 gcloud CLI，方法是執行 gcloud init 或 gcloud auth login，或是使用 Cloud Shell，後者會自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID"

PowerShell (Windows)

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID",
  "createTime": CREATE_TIME,
  "startTime": START_TIME,
  "updateTime": UPDATE_TIME,
  "state": "SUCCEEDED",
  "dvrManifests": [
    {
      "manifestKey": "manifest_hls",
      "outputUri": "gs://BUCKET_NAME/dvr/DVR_SESSION_ID/main.m3u8"
    }
  ],
  "dvrWindows": [
    {
      "timeInterval": {
        "startTime": "INTERVAL_START_TIME",
        "endTime": "INTERVAL_END_TIME"
      }
    }
  ]
}

當第一個片段根據父管道的 retentionConfig 到期時，系統會移除 DVR 工作階段和產生的資訊清單。如果您希望工作階段持續時間超過設定的保留時間，請改為建立頻道短片。

更新 DVR 工作階段

如要更新 DVR 工作階段，請使用 projects.locations.channels.dvrSessions.patch 方法。

以下範例會更新 DVR 工作階段使用的 DVR 時間回溯期。並非所有欄位都能更新，請參閱支援欄位清單。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_NUMBER：您的 Google Cloud 專案編號，位於 IAM 設定頁面上的「專案編號」欄位
• LOCATION：頻道所在位置；請使用支援的區域之一
  顯示地區
  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • us-west2
  • northamerica-northeast1
  • southamerica-east1
  • asia-east1
  • asia-east2
  • asia-south1
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1
  • europe-north1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
• CHANNEL_ID：管道的使用者定義 ID
• DVR_SESSION_ID：DVR 工作階段的使用者定義 ID
• INTERVAL_START_TIME：原始直播資訊清單中的 Unix Epoch 紀元時間；使用 RFC3339 世界標準時間「Zulu」格式的時間戳記 (例如 2014-10-02T15:01:23Z)
• INTERVAL_END_TIME：原始直播資訊清單中的 Mark-out Unix Epoch 時間；使用 RFC3339 世界標準時間「Zulu」格式的時間戳記 (例如 2014-10-02T15:01:23Z)

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意：以下指令假設您已使用使用者帳戶登入 gcloud CLI，方法是執行 gcloud init 或 gcloud auth login，或是使用 Cloud Shell，後者會自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，即可在目前目錄中建立或覆寫此檔案：

cat > request.json << 'EOF'
{
  "dvrWindows":[
    {
      "timeInterval": {
        "startTime": "INTERVAL_START_TIME",
        "endTime": "INTERVAL_END_TIME"
      }
    }
  ]
}
EOF

接著，執行下列指令來傳送 REST 要求：

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID?updateMask=dvrWindows"

PowerShell (Windows)

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

將要求主體儲存在名為 request.json 的檔案中。在終端機中執行下列指令，即可在目前目錄中建立或覆寫此檔案：

@'
{
  "dvrWindows":[
    {
      "timeInterval": {
        "startTime": "INTERVAL_START_TIME",
        "endTime": "INTERVAL_END_TIME"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

接著，執行下列指令來傳送 REST 要求：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID?updateMask=dvrWindows" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID",
    "verb": "update",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

這個指令會建立長期執行作業 (LRO)，您可以使用該作業追蹤要求的進度。詳情請參閱「管理長時間執行的作業 」。

如果DVR 工作階段狀態為 LIVE，且更新可能會覆寫目前的 DVR 資訊清單，系統會拒絕更新要求。唯一例外情況是，更新會縮短 DVR 工作階段 (例如將結束時間變更為現在或過去的某個時間)；在這種情況下，DVR 工作階段會立即停止，並進入 COOLDOWN 狀態。60 秒的冷卻期過後，系統會覆寫 DVR 資訊清單，以反映更新後的開始和結束時間。

列出 DVR 工作階段

如要列出為管道建立的所有 DVR 工作階段，請使用 projects.locations.channels.dvrSessions.list 方法。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_NUMBER：您的 Google Cloud 專案編號，位於 IAM 設定頁面上的「專案編號」欄位
• LOCATION：頻道所在位置；請使用支援的區域之一
  顯示地區
  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • us-west2
  • northamerica-northeast1
  • southamerica-east1
  • asia-east1
  • asia-east2
  • asia-south1
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1
  • europe-north1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
• CHANNEL_ID：管道的使用者定義 ID

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意：以下指令假設您已使用使用者帳戶登入 gcloud CLI，方法是執行 gcloud init 或 gcloud auth login，或是使用 Cloud Shell，後者會自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions"

PowerShell (Windows)

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "dvrSessions": [
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID",
      "createTime": CREATE_TIME,
      "startTime": START_TIME,
      "updateTime": UPDATE_TIME,
      "state": "SCHEDULED",
      "dvrManifests":[
        {
          "manifestKey": "manifest_hls",
          "outputUri": "gs://BUCKET_NAME/dvr/DVR_SESSION_ID/main.m3u8"
        }
      ],
      "dvrWindows":[
        {
          "timeInterval": {
            "startTime": "INTERVAL_START_TIME",
            "endTime": "INTERVAL_END_TIME"
          }
        }
      ]
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/my-other-DVR-session",
      "createTime": CREATE_TIME,
      "startTime": START_TIME,
      "updateTime": UPDATE_TIME,
      "state": "SCHEDULED",
      "dvrManifests":[
        {
          "manifestKey": "manifest_hls2",
          "outputUri": "gs://BUCKET_NAME/dvr/my-other-DVR-session/main.m3u8"
        }
      ],
      "dvrWindows":[
        {
          "timeInterval": {
            "startTime": "INTERVAL_START_TIME",
            "endTime": "INTERVAL_END_TIME"
          }
        }
      ]
    },
  ]
}

刪除 DVR 工作階段

如要刪除 DVR 工作階段，請使用 projects.locations.channels.dvrSessions.delete 方法。這個方法會刪除 DVR 工作階段工作和產生的資訊清單。Cloud Storage 值區中建立的資源會根據保留設定刪除。

使用任何要求資料之前，請先替換以下項目：

• PROJECT_NUMBER：您的 Google Cloud 專案編號，位於 IAM 設定頁面上的「專案編號」欄位
• LOCATION：頻道所在位置；請使用支援的區域之一
  顯示地區
  • us-central1
  • us-east1
  • us-east4
  • us-west1
  • us-west2
  • northamerica-northeast1
  • southamerica-east1
  • asia-east1
  • asia-east2
  • asia-south1
  • asia-northeast1
  • asia-southeast1
  • australia-southeast1
  • europe-north1
  • europe-west1
  • europe-west2
  • europe-west3
  • europe-west4
• CHANNEL_ID：管道的使用者定義 ID
• DVR_SESSION_ID：DVR 工作階段的使用者定義 ID

如要傳送要求，請展開以下其中一個選項：

curl (Linux、macOS 或 Cloud Shell)

注意：以下指令假設您已使用使用者帳戶登入 gcloud CLI，方法是執行 gcloud init 或 gcloud auth login，或是使用 Cloud Shell，後者會自動登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

curl -X DELETE \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID"

PowerShell (Windows)

注意：下列指令假設您已透過執行 gcloud init 或 gcloud auth login 登入 gcloud CLI。您可以執行 gcloud auth list 查看目前有效的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method DELETE `
    -Headers $headers `
    -Uri "https://livestream.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID" | Select-Object -Expand Content

您應該會收到如下的 JSON 回應：

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.video.livestream.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_NUMBER/locations/LOCATION/channels/CHANNEL_ID/dvrSessions/DVR_SESSION_ID",
    "verb": "delete",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

這個指令會建立長期執行作業 (LRO)，您可以使用該作業追蹤要求的進度。詳情請參閱「管理長時間執行的作業 」。