访问权限要求

用户更喜欢观看或收听他们已经可以访问的内容，例如现有的订阅内容。如果 Google 知道用户可以在您的应用或平台上访问哪些内容，则可以构建更好的搜索结果或回答，以便将用户引导至相应内容。

图 1. 访问权限要求可帮助您的订阅者访问您应用或平台中的内容。

确定内容访问权限要求

您必须为目录中的每个内容包指定访问权限要求。在执行此操作时，请考虑以下问题：

  • 用户是否需要登录您的应用或平台才能访问内容？

  • 用户是否需要订阅？

    仅限观看操作：

    • 用户是否需要订阅外部服务提供商的服务？
    • 您是否提供分级、多套餐或附加订阅？

  • 仅限观看操作：用户是否需要租借或购买内容？

  • 访问权限要求是否会随时间推移而变化？

  • 访问权限要求是否取决于设备位置？

访问权限限制类型

访问权限限制有两种：

付费墙类型

您可以按付费墙类型限制对内容的访问。下表详细介绍了不同的付费墙类型：

付费墙类型 示例 类别
无需购买或登录。 Crackle nologinrequired
用户必须登录，但无需付费订阅。 Vudu（广告型视频点播） free
用户必须拥有有效的订阅。访问权限与订阅层级无关。 Netflix

subscription
用户必须拥有有效的订阅。访问权限取决于订阅层级。 Hulu（附加服务）

subscription
购买后，内容在有限时间内可供访问。 Vudu rental
购买后，内容可无限期观看。 Vudu purchase
您可以通过有线电视订阅来观看这些内容。 HBO Go externalSubscription

观看操作的付费墙类型

如需为观看操作指定内容付费墙类型，请使用操作访问权限规范中的 category 属性：

"potentialAction": {
  "@type":"WatchAction",
  "target": { … },
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2018-06-01T10:35:29Z",
    "availabilityEnds": "2019-05-31T10:35:29Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  },
  ...
}

聆听操作的付费墙类型

如需为 Listen Action 指定内容付费墙类型，请在 offer 对象中使用 category 属性：

"potentialAction": {
  "@type":"ListenAction",
  "target": { … },
  "expectsAcceptanceOf":{
    "@type":"Offer",
    "category":"subscription",
    "availabilityStarts": "2018-06-01T10:35:29Z",
    "availabilityEnds": "2019-05-31T10:35:29Z",
    "eligibleRegion": {
      "@type":"Country",
      "name":"US"
    }
  },
  ...
}

地理区域

您必须指定内容的适用地理区域。请使用以下一个或两个属性：

如果设备位置位于 eligibleRegion 中指定的任何区域内，且不位于 ineligibleRegion 中指定的任何区域内，则用户可以访问内容。

eligibleRegion 和 ineligibleRegion 属性允许使用以下值：

如果内容在全球范围内提供，请为 eligibleRegion 使用以下特殊值：

"eligibleRegion": "EARTH",

eligibleRegion 用例

以下是 eligibleRegion 属性的用例示例：

  • 示例 1：包含国家/地区列表的 eligibleRegion。
  • 示例 2：eligibleRegion 包含包含邮政编码列表的 GeoShape 对象。
  • 示例 3：eligibleRegion 包含一个 GeoShape 对象，其中包含邮寄分拣区 (FSA) 代码列表。
  • 示例 4：eligibleRegion 包含包含 DMA ID 的 GeoShape 对象。
  • 示例 5：包含 GeoShape 对象列表的 eligibleRegion。每个都包含一个 DMA ID。
  • 示例 6：ineligibleRegion，其中邮政编码已被屏蔽。

示例 1

eligibleRegion 包含国家/地区列表：


"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/north_america_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "eligibleRegion": [
    {
      "@type": "Country",
      "name": "US"
    },
    {
      "@type": "Country",
      "name": "CA"
    }
  ]
}

示例 2

eligibleRegion，其中包含包含邮政编码列表的 GeoShape 对象：


"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "eligibleRegion": {
    "@type": "GeoShape",
    "@id": "http://example.com/area1",
    "addressCountry": "US",
    "postalCode": [
      "94118",
      "94119"
    ]
  }
}

示例 3

eligibleRegion，其中包含一个 GeoShape 对象，该对象包含邮寄分拣区 (FSA) 代码列表：


"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "eligibleRegion":{
    "@type": "GeoShape",
    "@id": "http://example.com/area2",
    "addressCountry": "CA",
    "postalCode": [
      "1A1",
      "K1A"
    ]
  }
}

示例 4

eligibleRegion，其中包含包含 DMA ID 的 GeoShape 对象：


"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/abcd/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
  "eligibleRegion":{
    "@type": "GeoShape",
    "@id": "http://example.com/area3",
    "addressCountry": "US",
    "identifier": [
      {
        "@type": "PropertyValue",
        "propertyID": "DMA_ID",
        "value": "501"
      }
    ]
  }
}

示例 5

包含 GeoShape 对象列表的 eligibleRegion。 每个都包含 DMA ID：


"actionAccessibilityRequirement" : {
   "@type" : "ActionAccessSpecification",
   "eligibleRegion" : [
      {
         "@id" : "http://example.com/dma/601",
         "@type" : "GeoShape",
         "addressCountry" : "US",
         "identifier" : {
            "@type" : "PropertyValue",
            "propertyID" : "DMA_ID",
            "value" : "601"
         }
      },
      {
         "@id" : "http://example.com/dma/602",
         "@type" : "GeoShape",
         "addressCountry" : "US",
         "identifier" : {
            "@type" : "PropertyValue",
            "propertyID" : "DMA_ID",
            "value" : "602"
         }
      }
   ]
}

示例 6

ineligibleRegion 邮政编码被遮盖：


"actionAccessibilityRequirement": {
  "@type": "ActionAccessSpecification",
  "category": "subscription",
  "requiresSubscription": {
    "@type": "MediaSubscription",
    "@id": "http://www.example.com/local_tv_network/subscription",
    "name": "Example Subscription",
    "commonTier": true
  },
 "eligibleRegion":   {
      "@type": "Country",
      "name": "US"
    },
  "ineligibleRegion": {
    "@type": "GeoShape",
    "@id": "http://example.com/area1",
    "addressCountry": "US",
    "postalCode": [
      "94118",
      "94119"
    ]
  }
}

使用权标识符

使用权标识符 entitlementId 是指表示对媒体目录中一组内容的访问权限的字符串。为了确定用户是否有权访问您的内容，Google 会执行以下步骤：

  1. 我们会向您的使用权端点发出 API 调用，以接收用户的使用权标识符。
  2. 我们会从您的 Media Actions Feed 中查找相应内容的必需使用权标识符。
  3. 我们会将用户的 entitlementId 与 Feed 中媒体订阅对象的 identifier 属性进行匹配。如果至少有一个 entitlementId 匹配，我们会确定用户可以访问相应内容。
图 2. 用户的某个使用权标识符与内容的必需使用权标识符匹配。

Google 建议您为 entitlementId 使用以下语法：

<domain name> + colon (:) + <access level to content>

语法示例：

  • example.com:basic
  • example.com:premium
  • example.com:sports

使用权标识符示例

MediaExampleCompany 的 Feed 指定 Movie XYZ 需要 example.com:basic entitlementId，如下所示：

{
  "@context": ["http://schema.org", {"@language": "en"}],
  "@type": "Movie",
  "@id": "www.example.com/movie_xyz",
  "url": "www.example.com/movie_xyz",
  "name": "Movie XYZ",
  "potentialAction": {
    "@type": "WatchAction",
    "target": [ … ],
    "actionAccessibilityRequirement": {
      "@type": "ActionAccessSpecification",
      "category": "subscription",
      "requiresSubscription": {
        "@type": "MediaSubscription",
        "@id": "http://www.example.com/basic_subscription",
        "name": "Basic subscription",
        "commonTier": true
        ...
      },
      ...
    }
  },
  ...
}

常见的访问权限使用场景

以下是常见的访问权限用例：

  • 免费（无需登录）：用户无需登录、订阅或购买即可使用相应内容。
  • 免费（需要登录）：用户需要登录才能观看内容，但无需订阅。
  • 单层级订阅：内容需要订阅。所有订阅者都可以访问相同的内容（无论是电影还是剧集），无论其订阅套餐如何。
  • 多层级订阅：内容需要订阅。订阅者可以根据其订阅层级访问不同的内容，无论是电影还是剧集。例如，银色与金色。
  • 插件订阅：需要订阅才能使用相应内容。订阅者可以在常规订阅的基础上添加付费内容。
  • 一次性购买：用户可以购买内容，然后无限期访问该内容。
  • 直播电视：订阅后，您可以观看本地、全国和付费频道。
  • 第三方订阅：用户需要使用其有线电视提供商的账号登录才能观看相应内容。

免费（无需登录）

无需登录

无需登录或订阅即可观看相应内容。


{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "nologinrequired",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
  • 将 category 设置为 nologinrequired。
  • 请勿包含 expectAcceptanceOf。

免费（需要登录）

需要登录

内容要求用户登录，但无需订阅。


{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "free",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
  • 将 category 设置为 free。
  • 请勿包含 expectAcceptanceOf。

单层级订阅

在单层级订阅模式中，服务提供商只有一个订阅层级。所有订阅者都可以访问相同的内容（无论是电影还是剧集），无论其订阅套餐如何。


{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "requiresSubscription": {
        "@type": "MediaSubscription",
        "name": "Example Package",
        "commonTier": true,
        "@id": "http://www.example.com/example_package"
    },
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}

多层级订阅

在分层订阅模式中，服务提供商提供多个订阅层级，例如黄金、白银和青铜。订阅更高层级的用户可以访问所有更低层级的内容。不过，订阅较低层级的用户无法访问较高层级的内容。

图 3. 分级订阅模式及其对使用权的表示。

请考虑以下场景：

  • Jane 订阅了黄金层级。您的使用权端点会返回以下 entitlementId 标识符：
    • example.com:bronze
    • example.com:silver
    • example.com:gold
  • John 订阅了青铜层级。您的使用权端点会返回以下 entitlementId：
    • example.com:bronze
  • 您的媒体广告系列 Feed 描述了以下要求：
    • 电影 A 需要 example.com:bronze。
    • 电影 B 需要 example.com:silver。

在此场景中，Google 会为 Jane 和 John 确定以下访问权限级别：

  • 简和约翰都可以访问电影 A。
  • 简可以访问电影 B，但约翰无法访问。
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "requiresSubscription": {
      "@type": "MediaSubscription",
      "@id": "http://www.example.com/basic_subscription",
      "name": "Bronze",
      "commonTier": true
      ...
    },
    ...
  }
}

附加服务订阅

在插件订阅模式中，服务提供商允许用户扩展其使用权并向基本订阅添加频道。用户可以根据需要添加任意数量的渠道。

图 4. 插件订阅模型及其对使用权的表示。

请考虑以下场景：

  • 除了基本版订阅外，Jane 还订阅了 PRO 和 Sportz。您的使用权端点会返回以下 entitlementId 标识符：
    • example.com:basic
    • example.com:pro
    • example.com:sportz
  • John 只有基本订阅。您的权限端点会返回以下 entitlementId：
    • example.com:basic
  • 您的媒体广告系列 Feed 描述了以下要求：
    • 电影 A 需要 example.com:basic。
    • 电影 B 需要 example.com:pro。

在此场景中，Google 会为 Jane 和 John 确定以下访问权限级别：

  • 简和约翰都可以访问电影 A。
  • 简可以访问电影 B，但约翰无法访问。
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    "requiresSubscription": [
      {
          "@type": "MediaSubscription",
          "@id": "https://www.example.com/package/basic",
          "name": "Basic",
          "sameAs": "https://www.example.com/package/basic",
          "commonTier": true
        },
        {
          "@type": "MediaSubscription",
          "@id": "https://www.example.com/packages/basic/pro",
          "name": "PRO",
          "sameAs": "https://www.example.com/package/pro",
          "identifier": "example.com:pro",
          "commonTier": false
        },
        {
          "@type": "MediaSubscription",
          "@id": "https://www.example.com/package/sportz",
          "name": "Sportz",
          "sameAs": "https://www.example.com/package/sports",
          "identifier": "example.com:sportz",
          "commonTier": false
        }
    }
  }
}

一次性购买

购买

购买后，内容可无限期观看。


{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "purchase",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 7.99,
      "priceCurrency": "USD",
      "seller": {
        "@type": "Organization",
        "name": "Example",
        "sameAs": "http://www.example.com/"
      }
    }
  }
}
  • 将 category 设置为 purchase。
  • 在 actionAccessibilityRequirement 中添加 expectAcceptanceOf 以指明购买交易的价格。

租赁

购买后，内容在有限时间内可供访问。


{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "rental",
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    },
    "expectsAcceptanceOf": {
      "@type": "Offer",
      "price": 7.99,
      "priceCurrency": "USD",
      "seller": {
        "@type": "Organization",
        "name": "Example",
        "sameAs": "http://www.example.com/"
      }
    }
  }
}
  • 将 category 设置为 rental。
  • 在 actionAccessibilityRequirement 中添加 expectAcceptanceOf 以指明租金。

电视直播

在媒体操作 Feed 中，您可以根据以下两种用户情况限制对直播电视频道或活动的访问权限：

  • 用户的设备位置信息

    如需限制对电视频道的访问，请指定用户可以访问该频道的区域。此条件通常适用于本地广播电视频道。

  • 用户的账号状态

    如果电视频道的访问权限取决于用户的账号级设置，请使用使用权标识符来表示限制。

    此条件通常适用于以下用例：

    • 套餐：全国性频道通常包含在套餐中，用户可以选择要订阅的套餐。
    • 附加频道：部分付费频道要求用户选择将额外的频道添加到其订阅中。
    • 区域性体育电视网络 (RSN)：RSN 通常与用户的“居住地”位置相关联。即使用户身在“居住地”以外的地方，也可以在 RSN 上观看内容。

第三方订阅

第三方订阅

订阅者可以通过其他服务观看相应内容。


{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "externalsubscription"
    "availabilityStarts": "2015-01-01T00:00Z",
    "availabilityEnds": "2015-12-31T00:00Z",
    "requiresSubscription":{
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/faq",
      "name": "Example",
      "sameAs": "https://www.example.com/faq",
      "authenticator": {
        "@type": "Organization",
        "name": "TVE"
      }
    },
    "eligibleRegion": {
      "@type": "Country",
      "name": "US"
    }
  }
}
  • 添加 authenticator 以指明其他服务对订阅者进行身份验证。例如，HBO GO 需要订阅有线电视提供商。

常规层级套餐

所有订阅者（无论其订阅套餐如何）都可以观看常规层级的内容。常规层级适用于 subscription 的 category 为 1 的所有内容。如需详细了解 category 属性，请参阅付费墙类型部分。

为什么需要常规层级软件包？

多款 Google 产品都会向用户提供电视和电影推荐；其中包括 Google 搜索、Android TV 和 Google 助理。为了让用户对费用有合理的预期，Google 必须了解所有订阅者通过使用常规层级可以观看哪些内容。Google 还必须了解订阅特定订阅套餐的订阅者可以使用哪些内容。

除非您支持 entitlement API，否则 Google 会推荐常规层级中提供的影视内容。借助此 API，Google 可以了解每个特定用户可以访问的非常规层级影视内容。

何时应创建通用层级软件包？

如果您的服务提供面向所有订阅者的内容，则必须提供通用层级套餐。这包括仅提供一个软件包的服务，以及提供多个软件包或插件的服务。

如果提供商没有面向所有订阅者提供的内容，则无需创建通用层级套餐。例如，服务提供商在其所有套餐中提供互斥内容。

常见层级示例

以下是常规层级的示例。

分层订阅

在分层订阅模式中，服务提供商提供多个订阅层级，例如黄金、白银和青铜层级。订阅高级别服务的用户可以访问低级别服务提供的所有内容。订阅较低层级的用户无权访问较高层级的内容。下图展示了软件包结构示例。

黄金层级包含白银层级的所有内容，而白银层级本身包含青铜层级的所有内容。
图 5. 分层订阅套餐结构。

在以下代码示例中，青铜版套餐是常规层级，因为所有用户都可以访问该层级中的所有内容。

"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/bronze",
      "name": "Bronze",
      "sameAs": "https://www.example.com/package/bronze",
      "commonTier": true
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/silver",
      "name": "Silver",
      "sameAs": "https://www.example.com/package/silver",
      "identifier": "example.com:silver",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/gold",
      "name": "Gold",
      "sameAs": "https://www.example.com/package/gold",
      "identifier": "example.com:gold",
      "commonTier": false
    }
  ],

附加内容

在插件订阅模式中，服务提供商允许用户扩展其使用权，并向基本订阅添加频道。用户可以根据需要添加任意数量的渠道。以下图片展示了软件包结构示例。

每位用户都将从“基本”频道开始，然后可以选择添加 PRO、Sportz 和 Moviemax 频道的任意组合。
图 6. 插件订阅软件包结构。

如果您有一个面向所有用户且无需付费的渠道，则可以将该渠道与常规层级的渠道合并。

在以下代码示例中，基本文件包是常规层级，因为所有用户都可以访问此文件包中的所有内容。

"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/basic",
      "name": "Basic",
      "sameAs": "https://www.example.com/package/basic",
      "commonTier": true
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/packages/basic/pro",
      "name": "PRO",
      "sameAs": "https://www.example.com/package/pro",
      "identifier": "example.com:pro",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/sportz",
      "name": "Sportz",
      "sameAs": "https://www.example.com/package/sports",
      "identifier": "example.com:sportz",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/moviemax",
      "name": "Moviemax",
      "sameAs": "https://www.example.com/package/moviemax",
      "identifier": "example.com:moviemax",
      "commonTier": false
    }
  ],

内容重叠的软件包

在内容模型中，如果软件包包含重叠的内容，则服务提供商会销售包含其他软件包中部分内容的软件包。以下图片是软件包结构示例。

一个维恩图，其中软件包 1、2 和 3 之间的重叠部分标记为“通用层级”。
图 7. 包含重叠内容的软件包结构。

在以下代码示例中，提供商提供了三个软件包，其中部分内容在所有软件包中都有。在本例中，需要第四个代表通用层级的软件包。该文件必须包含所有三个文件包中提供的所有内容。

"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/1",
      "name": "Package 1",
      "sameAs": "https://www.example.com/package/1",
      "identifier": "example.com:package1",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/2",
      "name": "Package 2",
      "sameAs": "https://www.example.com/package/2",
      "identifier": "example.com:package2",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/3",
      "name": "Package 3",
      "sameAs": "https://www.example.com/package/3",
      "identifier": "example.com:package3",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/common",
      "name": "Common Tier Package",
      "sameAs": "https://www.example.com/package/common",
      "commonTier": true
    }
  ],

不含重叠内容的软件包

在所有内容包都不重叠的内容模型中，服务提供商销售的包不包含其他包中的内容。以下图片是软件包结构示例。

文件包 1、2 和 3 是完全独立的。
图 8. 软件包结构不含重叠内容。

在以下示例中，提供商提供三个软件包，其中没有任何内容在所有软件包中重叠。无需常规层级软件包。

"requiresSubscription": [
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/1",
      "name": "Package 1",
      "sameAs": "https://www.example.com/package/1",
      "identifier": "example.com:package1",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/2",
      "name": "Package 2",
      "sameAs": "https://www.example.com/package/2",
      "identifier": "example.com:package2",
      "commonTier": false
    },
    {
      "@type": "MediaSubscription",
      "@id": "https://www.example.com/package/3",
      "name": "Package 3",
      "sameAs": "https://www.example.com/package/3",
      "identifier": "example.com:package3",
      "commonTier": false
    }
  ],

使用权端点

使用本部分中的信息托管一个 HTTPS 端点，该端点会返回与用户关联的权限。

前提条件

在开始之前，请先验证您的服务是否支持与 Google 进行 OAuth 2.0 流程。

请求

如需接收用户的使用权限，Google 会发送包含用户 OAuth 令牌的请求。您的端点需要根据该 OAuth 令牌识别用户。请参阅以下示例：

GET /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer <OAuthToken>

响应

您的端点需要返回具有以下属性的响应：

属性
subscription

必需

这是根响应中的字段。
subscription.type

必需

此属性可以具有以下值：

  • ActiveSubscription：用户对提供商有有效订阅。
  • ActiveTrial：用户正在试用该提供商的服务。
  • InactiveSubscription：用户没有有效的订阅或有效的试用期。
subscription.expiration_date

可选

此使用权的到期日期，采用 ISO 8601 格式，其中包含时区。如需了解详情，请参阅到期日期。
entitlements

可选

此根属性包含用户持有的 entitlementId 值。
entitlements.entitlement

如果对在线播放目录的访问权限因订阅类型而异，则此属性为必需属性。

此属性包含 entitlementId。如需了解详情，请参阅使用权标识符。
entitlements.expiration_date

可选

此订阅的到期日期，采用 ISO 8601 格式，包括时区。如需了解详情，请参阅到期日期。

失效日期

端点响应中包含两个用于处理到期日期的属性：subscription.expiration_date 和 entitlements.expiration_date。您可以添加其中一个，也可以不添加这两个，但不能同时添加这两个。您使用哪种方法取决于您的订阅模式。

订阅模式
所有订阅者对您的在线影视内容目录的访问权限都是相同的。 由于您无需指定 entitlements 属性，因此请指定 subscription.expiration_date。

用户对您的在线播放目录的访问权限因用户订阅的详细信息而异。

如果您的订阅模式包含多个层级或会随着时间推移而过期的附加服务，请执行以下任一操作：

  • 如果所有 entitlements.entitlement 值都同时过期，请指定 subscription.expiration_date。
  • 如果某些 entitlements.entitlement 值的到期时间不同，请指定 entitlements.expiration_date。

示例回复

以下是不同订阅状态的示例响应：

  • 有效订阅
  • 有效订阅（具有到期日期）
  • 无订阅项目
  • 订阅了多个层级或附加服务

有效订阅

有效订阅

用户对 example.com 拥有有效订阅。在这种情况下，所有订阅者都可以访问您的整个在线影视内容目录，无论其订阅类型如何。


{
  "subscription" : {
    "type": "ActiveSubscription",
  }
}

有效订阅（具有到期日期）

有效订阅（设有到期日期）

用户订阅了 example.com，且订阅有到期日期。在这种情况下，所有订阅者（无论订阅类型如何）都可以访问您的整个在线影视内容目录。


{
  "subscription" : {
    "type": "ActiveSubscription",
    "expiration_date": "2019-11-10T10:00:00Z"
  }
}

无订阅项目

无订阅

用户没有订阅 example.com。


{
  "subscription" : {
    "type": "InactiveSubscription"
  }
}

订阅了多个层级或附加服务

订阅了多个层级或插件

用户订阅了 example.com:premium，订阅有效期到特定日期。


{
  "subscription" : {
    "type": "ActiveSubscription",
  }
  "entitlements": [
    {
      "entitlement": "example.com:premium",
      "expiration": "2019-11-10T10:00:00Z"
    }
  ]
}

速率限制

Google 最多每 6 小时刷新一次用户的使用权信息。为了平滑每秒查询次数 (QPS) 上限，Google 会在一定时间内将查询均匀分布到您的端点。因此，您可以使用以下公式估算端点的预期平均 QPS：

预计平均 QPS = <用户总数> / 21,600 秒（6 小时 x 60 分钟 x 60 秒）

如果您有大量用户，Google 可以调整 6 小时的间隔时间。如有必要，请与 Google 联系以讨论配置。

与 Google 联系

端点准备就绪后，请与 Google 联系，告知端点的网址。

操作访问权限规范属性

如需参考信息，请参阅Action 访问权限规范属性部分。