實作：影片

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

擷取頻道上傳的影片

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

這個範例說明如何擷取 YouTube 最熱門影片清單，這些影片是透過演算法選出，該演算法結合多種不同信號來判斷整體熱門程度。

如要擷取熱門影片清單，請呼叫 videos.list 方法，並將 chart 參數的值設為 mostPopular。 mostPopular排行榜包含發燒音樂、電影和遊戲影片。

接著，您可以視需要設定下列參數：

  • regionCode：指示 API 傳回指定區域的影片清單。參數值為 ISO 3166-1 alpha-2 國家/地區代碼。您可以使用 i18nRegions.list 方法，擷取 YouTube 支援的國家/地區代碼清單。
  • videoCategoryId：指定要擷取最熱門影片的影片類別。您可以使用 videoCategories.list 方法，擷取 YouTube 支援的類別 ID 清單。

舉例來說，下列要求會擷取西班牙最熱門的運動影片：

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

擷取批次影片統計資料

這個範例會使用 videos.batchGetStats 方法，擷取影片清單的統計資料。

如要使用這個方法，請將要求的 id 參數設為以半形逗號分隔的 YouTube 影片 ID 清單，指定要擷取哪些影片的統計資料。將 part 參數的值設為以半形逗號分隔的 videoStat 資源部分清單，回應中就會包含這些部分。支援的部分為 snippet、statistics、contentDetails 和 id。

如要對非公開影片使用這個方法，必須先通過驗證，但公開影片則不需要。如果要求會擷取任何非公開影片的資料，則必須經過適當的授權。

以下請求會擷取影片 ID VIDEO_ID_1 和 VIDEO_ID_2 的統計資料：

https://developers.google.com/apis-explorer/#p/youtube/v3/youtube.videos.batchGetStats?
        part=snippet,statistics
        &id=VIDEO_ID_1,VIDEO_ID_2

上傳影片

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

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

  • 支援續傳的上傳作業指南說明應用程式使用支援續傳的上傳程序上傳影片時，所使用的 HTTP 要求序列。本指南主要適用於無法使用 Google API 用戶端程式庫的開發人員，因為部分程式庫提供支援續傳的上傳作業的原生支援功能。

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

查看上傳影片的狀態

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

注意：應用程式可以輪詢 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

創作者發起的品牌合作夥伴存取權 (CI BPA) 可讓影片擁有者與品牌合作夥伴頻道分享影片存取權。這需要 brandPartner 部分。

建立存取權 (插入)

如要在上傳影片時建立存取權，請在 part 參數中加入 brandPartner，並在要求主體中提供 brandPartner 物件。您必須指定 channelId (開頭為「UC」的外部頻道 ID) 或 channelHandle (開頭為「@」)，才能識別品牌頻道。

POST /youtube/v3/videos?part=snippet,status,brandPartner
{
  "snippet": {
    "title": "Video Title",
    "description": "Video Description",
    "categoryId": "22"
  },
  "status": {
    "privacyStatus": "private"
  },
  "brandPartner": {
    "channelHandle": "@brandchannel"
  }
}

回應中只會傳回已解析的 channelId。

更新或移除存取權 (更新)

如要更新其他品牌頻道的存取權，或移除存取權，請呼叫 videos.update 方法，並在 part 參數中加入 brandPartner。

如要取代存取權，請在要求主體中提供新的 channelId 或 channelHandle：

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {
    "channelId": "UC_SOME_BRAND_CHANNEL_ID"
  }
}

如要移除存取權，請傳送要求，並在 part 參數中加入 brandPartner，但要求主體中的 brandPartner 物件必須留空：

PUT /youtube/v3/videos?part=brandPartner
{
  "id": "VIDEO_ID",
  "brandPartner": {}
}

上傳自訂縮圖並設為影片縮圖

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

由於 APIs Explorer 不支援上傳媒體檔案 (此方法需要上傳媒體檔案)，因此無法使用 APIs Explorer 測試這項查詢。

相關程式碼範例：PHP、Python

刪除影片

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

  • 步驟 1：擷取影片 ID

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

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

  • 步驟 2：刪除影片

    呼叫 videos.delete 方法即可刪除特定影片。在要求中，id 參數會指定要刪除的影片 ID。要求必須使用 OAuth 2.0 授權。如要在 APIs 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