实现：视频

以下示例展示了如何使用 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 部分来检查已上传视频的状态，以及如何处理已上传视频的状态更改。

检查已上传视频的状态

此示例展示了如何检查已上传视频的状态。已上传的视频会立即显示在经过身份验证的用户的已上传视频 Feed 中。不过，在处理完毕之前，该视频不会在 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

借助由创作者发起的品牌合作伙伴访问权限 (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。

更新或移除访问权限（更新）

如需更新对其他品牌频道的访问权限，或移除访问权限，请在 part 参数中使用 brandPartner 调用 videos.update 方法。

如需替换访问权限，请在请求正文中提供新的 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

    向 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