存取權需求

使用者偏好觀看或收聽自己已可存取的內容，例如現有的訂閱內容。如果 Google 知道使用者可在您的應用程式或平台上存取哪些內容，就能建立更優質的搜尋結果或回覆，將使用者導向該內容。

圖 1. 存取權規定可協助訂閱者存取應用程式或平台上的內容。

找出內容存取權要求

你必須指出目錄中每個內容套件的存取權要求。請考量以下問題：

  • 使用者是否需要登入應用程式或平台才能存取內容？

  • 使用者是否需要訂閱？

    僅限觀看動作：

    • 使用者是否需要訂閱外部服務供應商的服務？
    • 您是否提供分級、多種套裝方案或加購訂閱方案？

  • 僅限 Watch Actions：使用者是否需要租借或購買內容？

  • 存取權要求是否會隨時間而變更？

  • 存取權要求是否取決於裝置位置？

存取權限制類型

存取權限制有兩種：

付費牆類型

你可以根據付費牆類型限制內容存取權。下表詳細說明各種付費牆類型：

付費牆類型 範例 類別
無須購買或登入帳戶。 Crackle nologinrequired
使用者必須登入，但不需要付費訂閱。 Vudu (廣告制隨選影片) free
使用者必須擁有有效訂閱。存取權與訂閱層級無關。 Netflix

subscription
使用者必須擁有有效訂閱。存取權取決於訂閱層級。 Hulu (外掛程式)

subscription
使用者可在購買後一段時間內存取這本書。 Vudu rental
購買後，內容可無限期觀看。 Vudu purchase
這類內容必須透過有線電視訂閱才能觀看。 HBO GO externalSubscription

收視活動的付費牆類型

如要指定 Watch Actions 的內容付費牆類型，請在動作存取規格中使用 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 Actions 的內容付費牆類型，請在 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： eligibleRegion 包含 GeoShape 物件清單。每個都包含 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 與包含轉發區號 (FSA) 代碼清單的 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/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

eligibleRegion 包含 GeoShape 物件的清單。每個都包含 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"
    ]
  }
}

授權 ID

授權 ID entitlementId 是指代表媒體目錄中一組內容存取權的字串。如要判斷使用者是否有權存取您的內容，Google 會採取下列步驟：

  1. 我們會向您的授權端點呼叫 API，接收使用者的授權 ID。
  2. 我們會從媒體動作動態饋給中查詢內容所需的授權 ID。
  3. 我們會將使用者的 entitlementId 比對至動態饋給中 media subscription 物件的 identifier 屬性。如果至少有一個 entitlementId 相符，我們就會判斷使用者可以存取內容。
圖 2. 使用者的其中一個授權 ID 與內容所需的授權 ID 相符。

Google 建議您使用下列語法來使用 entitlementId：

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

語法範例：

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

授權 ID 範例

MediaExampleCompany 動態饋給指定 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
        ...
      },
      ...
    }
  },
  ...
}

常見的存取用途

以下是常見的存取用途：

  • 免費 (無須登入)：使用者無須登入、訂閱或購買，即可觀看內容。
  • 免費 (需要登入)：使用者必須登入才能觀看內容，但不需訂閱。
  • 單一層級訂閱：需要訂閱才能觀看內容。無論訂閱方案為何，所有訂閱者都能存取相同的內容 (電影或劇集)。
  • 多層級訂閱：使用者必須訂閱才能觀看內容。訂閱者可以根據訂閱層級，存取不同的內容 (電影或劇集)。例如 Silver 與 Gold。
  • 外掛程式訂閱：使用者必須訂閱才能存取內容。訂閱者可以將付費內容加入一般訂閱項目。
  • 一次性購買：使用者可以購買內容，並在購買後無限期存取內容。
  • 直播電視：訂閱後即可收看當地、全國和付費頻道。
  • 第三方訂閱：使用者必須使用有線電視供應商的帳戶登入才能觀看內容。

免費 (不需登入)

不需登入

無須登入或訂閱即可觀看內容。


{
  "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 訂閱了 Gold 方案。您的授權端點會傳回下列 entitlementId ID：
    • example.com:bronze
    • example.com:silver
    • example.com:gold
  • 大明訂閱的是銅級方案。您的授權端點會傳回下列 entitlementId：
    • example.com:bronze
  • 媒體動作動態饋給說明以下規定：
    • 電影 A 需要 example.com:bronze。
    • 電影 B 需要 example.com:silver。

在這個情境中，Google 會為 Jane 和 John 決定下列存取層級：

  • Jane 和 John 都能觀看 Movie A。
  • Jane 可以觀看電影 B，但 John 無法觀看。
{
  "actionAccessibilityRequirement": {
    "@type": "ActionAccessSpecification",
    "category": "subscription",
    "requiresSubscription": {
      "@type": "MediaSubscription",
      "@id": "http://www.example.com/basic_subscription",
      "name": "Bronze",
      "commonTier": true
      ...
    },
    ...
  }
}

附加訂閱

在加購訂閱模式中，服務供應商可讓使用者擴充授權，並在基本訂閱方案中新增頻道。使用者可以視需要新增任意數量的管道。

圖 4. 外掛程式訂閱模式及其授權表示法。

請參考下列情境：

  • 除了Basic 訂閱方案，小珍還訂閱了 PRO 和 Sportz。您的授權端點會傳回下列 entitlementId ID：
    • example.com:basic
    • example.com:pro
    • example.com:sportz
  • John 僅訂閱Basic 方案。您的授權端點會傳回下列 entitlementId：
    • example.com:basic
  • 媒體動作動態饋給會說明下列規定：
    • 電影 A 需要 example.com:basic。
    • 電影 B 需要 example.com:pro。

在這個情境中，Google 會為 Jane 和 John 決定下列存取層級：

  • Jane 和 John 都能觀看 Movie A。
  • Jane 可以觀看電影 B，但 John 無法觀看。
{
  "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，以表示租賃價格。

電視直播

在媒體動作動態消息中，你可以根據下列兩種使用者條件，限制存取直播電視頻道或事件：

  • 使用者的裝置位置

    如要限制電視頻道的存取權，請指定使用者可存取的區域。這項條件通常適用於當地電視頻道。

  • 使用者的帳戶狀態

    如果電視頻道的存取權取決於使用者的帳戶層級設定，請使用授權 ID 代表限制。

    這項條件通常適用於下列用途：

    • 套裝方案：套裝方案通常會包含國家/地區管道，使用者可以選擇要訂閱哪些套裝方案。
    • 加購內容：部分付費頻道需要使用者選擇加入額外頻道才能訂閱。
    • 地方體育電視網 (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如要進一步瞭解 category 屬性，請參閱「付費牆類型」一節。

為什麼需要通用層級套裝方案？

多項 Google 產品會為使用者提供電視和電影建議，包括 Google 搜尋、Android TV 和 Google 助理。為了讓使用者瞭解費用，Google 必須瞭解所有訂閱者透過一般層級可觀看的內容。Google 也必須瞭解訂閱特定訂閱方案的訂閱者可觀看哪些內容。

除非您支援授權 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
    }
  ],

外掛程式

在加購訂閱模式中，服務供應商可讓使用者擴充權益，並在基本訂閱方案中新增頻道。使用者可以新增任意數量的管道。下圖為套件結構的範例。

每位使用者一開始都會使用 Basic 頻道，並可選擇新增 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 的重疊部分標示為「Common Tier」。
圖 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。詳情請參閱「授權 ID」。
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 最多每六小時重新整理一次使用者的授權資訊。為了平衡每秒查詢次數 (QPS) 上限，Google 會隨著時間的推移，將查詢平均分配至端點。因此，您可以使用以下公式，估算端點的預期平均 QPS：

預期的平均 QPS = <使用者總數>/ 21,600 秒 (6 小時 x 60 分鐘 x 60 秒)

如果您服務的使用者人數眾多，Google 可以調整 6 小時的間隔。如有需要，請與 Google 聯絡討論設定。

與 Google 聯絡

端點準備就緒後，請與 Google 聯絡，告知端點的網址。

動作存取權規格屬性

如需參考資訊，請參閱「動作存取權規格屬性」一節。