導入：影片

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

擷取頻道上傳的影片

這個範例擷取了上傳至特定頻道的影片，這個範例包含兩個步驟：

這個範例說明如何透過結合多種不同信號的演算法，在 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

上傳影片

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

  • API video.insert 方法的說明文件包含多種程式碼範例，說明如何使用各種程式設計語言上傳影片。

  • 續傳上傳作業指南說明瞭應用程式透過支援續傳的上傳程序上傳影片的 HTTP 要求順序。本指南的適用對象為無法使用 Google API 用戶端程式庫的開發人員，其中部分 API 提供了支援續傳的上傳作業。

  • 上傳影片的 JavaScript 範例會使用 CORS (跨來源資源分享) 示範透過網頁上傳影片檔案。vRS API 使用的 CORS 上傳程式庫自然地支援續傳的上傳作業。此外，這個範例示範如何擷取 video 資源的 processingDetails 部分，以及如何處理已上傳影片的狀態變更，藉此查看已上傳的影片狀態。

查看已上傳影片的狀態

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

  • 步驟 1：上傳影片

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

  • 步驟 2：查看影片狀態

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

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

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

    以下要求會檢查影片狀態。如要在 API 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"
  }
}

    如要在 API Explorer 中完成要求，您必須設定 id 屬性的值。

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.update?
        part=snippet

上傳自訂縮圖並設為影片

您可以使用 v3 API 的 thumbnails.set 方法上傳自訂縮圖，並將其設為影片。在要求中，videoId 參數值可用來識別要使用縮圖的影片。

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 物件。如要測試查詢，您必須以 videoId 屬性值取代有效的影片 ID。請注意，提交這項要求確實會檢舉影片。

    https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.reportAbuse