本頁面由 Cloud Translation API 翻譯而成。

實作：影片

以下範例說明如何使用 YouTube Data API (第 3 版) 執行與影片相關的功能。

擷取頻道上傳的影片

這個範例會擷取上傳到特定頻道的影片。這個範例有兩個步驟：

步驟 1：擷取頻道上傳影片的播放清單 ID

呼叫 channels.list 方法，擷取包含頻道上傳影片的播放清單 ID。請求的 part 參數值必須包含 contentDetails，做為要擷取的 channel 資源部分之一。在 API 回應中，contentDetails.relatedPlaylists.uploads 屬性包含播放清單 ID。

您可以透過下列幾種方式識別管道：
- 將 mine 參數值設為 true，即可擷取目前已驗證使用者的 YouTube 頻道資訊。您的要求必須使用 OAuth 2.0 授權。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &mine=true
```
- 將 forUsername 參數設為 YouTube 使用者名稱，即可擷取與該使用者名稱相關聯的頻道資訊。這個範例將 forUsername 參數值設為 Google，以便擷取 Google 官方 YouTube 頻道的資訊。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &forUsername=Google
```
- 將 id 參數設為 YouTube 頻道 ID，即可明確識別要擷取資訊的頻道。這個範例將 id 參數設為 UCK8sQmJBp8GCxrOtXWBpyEA，這也是 Google 官方 YouTube 頻道的 ID。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.channels.list?
        part=contentDetails
        &id=UCK8sQmJBp8GCxrOtXWBpyEA
```
步驟 2：擷取已上傳影片的清單

呼叫 playlistItems.list 方法，擷取已上傳影片的清單。將 playlistId 參數的值設為在步驟 1 中取得的值。在這個範例中，參數值設為 UUK8sQmJBp8GCxrOtXWBpyEA，也就是上傳到 Google 官方 YouTube 頻道的影片清單。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.playlistItems.list?
        part=snippet,contentDetails,status
        &playlistId=UUK8sQmJBp8GCxrOtXWBpyEA
```

擷取最熱門的影片

本例說明如何擷取 YouTube 最熱門影片清單，系統會使用演算法結合多種信號，判斷整體熱門程度。

如要擷取最受歡迎的影片清單，請呼叫 videos.list 方法，並將 chart 參數的值設為 mostPopular。擷取這份清單時，您也可以設定下列任一或兩個參數：

regionCode：指示 API 傳回指定區域的影片清單。
videoCategoryId：指出應擷取熱門影片的影片類別。

以下要求會擷取西班牙最受歡迎的體育影片：

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.search.list?
        part=snippet
        &chart=mostPopular
        &regionCode=es
        &videoCategoryId=17

上傳影片

由於 API Explorer 不支援上傳檔案，因此此說明不會連結至可執行的範例。下列資源可協助您修改應用程式，讓應用程式能夠使用 v3 API 上傳影片：

API 的 videos.insert 方法說明文件包含多個程式碼範例，說明如何使用不同程式設計語言上傳影片。
「續傳上傳」指南說明瞭應用程式使用支援續傳的上傳程序上傳影片時，所使用的 HTTP 要求順序。本指南主要適用於無法使用 Google API 用戶端程式庫 (其中部分程式庫原生支援可暫停上傳功能) 的開發人員。
上傳影片的 JavaScript 範例會使用 CORS (跨來源資源共享)，示範如何透過網頁上傳影片檔案。第 3 版 API 使用的 CORS 上傳程式庫自然支援可續傳上傳功能。此外，本範例會示範如何透過擷取 video 資源的 processingDetails 部分，檢查已上傳影片的狀態，以及如何處理已上傳影片的狀態變更。

查看上傳影片的狀態

本範例說明如何查看已上傳影片的狀態。上傳的影片會立即顯示在已驗證使用者的上傳影片動態消息中。不過，影片必須先經過處理，才能在 YouTube 上顯示。

步驟 1：上傳影片

呼叫 videos.insert 方法來上傳影片。如果要求成功，API 回應會包含 video 資源，用於識別上傳影片的專屬影片 ID。
步驟 2：查看影片狀態

呼叫 videos.list 方法，查看影片狀態。將 id 參數的值設為在步驟 1 中取得的影片 ID。將 part 參數的值設為 processingDetails。

如果要求順利處理，API 回應就會包含 video 資源。請檢查 processingDetails.processingStatus 屬性的值，判斷 YouTube 是否仍在處理影片。當 YouTube 處理完影片後，這個屬性的值就會變更為 processing 以外的值，例如 succeeded 或 failed。

要求主體是 video 資源，其中 id 屬性會指定要刪除的影片 ID。在本例中，資源也包含 recordingDetails 物件。

以下要求會檢查影片的狀態。如要在 APIs Explorer 中完成要求，您必須設定 id 屬性的值。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.list?
        part=snippet,processingDetails
        &id=VIDEO_ID
```

注意：應用程式可以輪詢 API，定期檢查新上傳影片的狀態。影片處理完畢後，應用程式可以根據影片狀態建立公告或執行其他動作。

更新影片

以下範例說明如何更新影片，新增影片錄製時間和地點的資訊。這個範例包含以下步驟：

步驟 1：擷取影片 ID

請按照上述步驟，為目前已驗證的使用者頻道擷取已上傳的影片。這份清單可用於顯示影片清單，並將每部影片的 ID 做為索引。

注意：取得影片 ID 的方法有很多種，例如擷取搜尋結果或列出播放清單中的項目。不過，由於只有影片擁有者可以更新影片，因此在這個程序中，第一步可能會是擷取授權 API 要求的使用者所擁有的影片清單。
步驟 2：更新影片

呼叫 videos.update 方法來更新特定影片。將 part 參數的值設為 recordingDetails。(參數值取決於要更新哪些影片的中繼資料欄位)。

要求主體是 video 資源，其中 id 屬性會指定要更新的影片 ID。在本例中，資源也包含 recordingDetails 物件。

以下資源範例指出影片是在 2013 年 10 月 30 日在波士頓錄製：
```
{
  "id": "VIDEO_ID",
  "recordingDetails": {
    "location": {
      "latitude": "42.3464",
      "longitude": "-71.0975"
    }
    "recordingDate": "2013-10-30T23:15:00.000Z"
  }
}
```
如要在 APIs Explorer 中完成要求，您必須設定 id 屬性的值。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet
```

上傳自訂縮圖圖片，並將其設為影片縮圖

你可以使用 v3 API 的 thumbnails.set 方法上傳自訂縮圖圖片，並為影片設定縮圖。在要求中，videoId 參數的值會標示要使用縮圖的影片。

這個查詢無法使用 APIs Explorer 進行測試，因為 APIs Explorer 不支援上傳媒體檔案，而這正是此方法的必要條件。

相關程式碼範例：PHP、Python

刪除影片

以下範例說明如何刪除影片。這個範例包含以下步驟：

步驟 1：擷取影片 ID

請按照上述步驟，為目前已驗證的使用者頻道擷取已上傳的影片。這份清單可用於顯示影片清單，並將每部影片的 ID 做為索引。

注意：取得影片 ID 的方法有很多種，例如擷取搜尋結果或列出播放清單中的項目。不過，由於只有影片擁有者才能刪除影片，因此在這個程序中，第一步應該是擷取授權 API 要求的使用者所擁有的影片清單。
步驟 2：刪除影片

呼叫 videos.delete 方法即可刪除特定影片。在要求中，id 參數會指定要刪除的影片 ID。要求必須使用 OAuth 2.0 授權。如果您要在 API Explorer 中測試這項查詢，請將有效的影片 ID 替換為 id 參數值。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.delete?
        id=VIDEO_ID
```

以下範例說明如何檢舉含有濫用行為的影片。這個範例包含以下步驟：

步驟 1：擷取可說明影片遭檢舉原因的 ID

向 videoAbuseReportReasons.list 方法傳送授權要求，擷取標記影片的有效原因清單。以下的 videoAbuseReportReason 範例資源包含標記含有垃圾內容或誤導性內容的影片相關資訊。

{
  "kind": "youtube#videoAbuseReportReason",
  "etag": "\"tbWC5XrSXxe1WOAx6MK9z4hHSU8/Or2VqBIilpHU7j__oPzUFCvGVBw\"",
  "id": "S",
  "snippet": {
    "label": "Spam or misleading",
    "secondaryReasons": [
      {
        "id": "27",
        "label": "Spam or mass advertising"
      },
      {
        "id": "28",
        "label": "Misleading thumbnail"
      },
      {
        "id": "29",
        "label": "Malware or phishing"
      },
      {
        "id": "30",
        "label": "Pharmaceutical drugs for sale"
      },
      {
        "id": "31",
        "label": "Other misleading info"
      }
    ]
  }
}

如資源所示，這個原因與次要原因清單相關聯。檢舉含有垃圾內容的影片時，請提供 ID 和原因，並建議提供次要原因。

步驟 2：檢舉影片中的不當內容

向 videos.reportAbuse 方法傳送授權要求，實際檢舉影片。要求主體是 JSON 物件，可用來識別遭標記的影片，以及遭標記的原因。如步驟 1 所述，系統支援並強烈建議提供次要原因，以便處理某些類型的申訴。
JSON 物件的 videoId 屬性會標示遭檢舉的影片。

以下 JSON 物件範例會將影片標記為含有垃圾內容或誤導性內容，更具體來說，是因為使用誤導性縮圖。如上方的 JSON 物件範例所示，垃圾內容或誤導性內容的 ID 為 S。「縮圖與內容不符」的 ID 為 28。
```
{
  "videoId": "VIDEO_ID",
  "reasonId": "S",
  "secondaryReasonId": "28",
  "comments": "Testing the video flagging feature.",
  "language": "en"
}
```
videos.reportAbuse 要求必須使用 OAuth 2.0 授權。下方連結會在 APIs Explorer 中載入上述 JSON 物件。如要測試查詢，請將有效的影片 ID 替換為 videoId 資源值。請注意，提交這項要求後，系統會將影片標記為違規。
```
https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse
```