REST Resource: operators.clients.users.planStatus

資源：PlanStatus

PlanStatus 包含使用者購買的所有頂層行動服務套件詳細資料。

JSON 表示法 
{
  "name": string,
  "plans": [
    {
      object (Plan)
    }
  ],
  "languageCode": string,
  "expireTime": string,
  "updateTime": string,
  "title": string,
  "subscriberId": string,
  "accountInfo": {
    object (AccountInfo)
  },
  "uiCompatibility": enum (UiCompatibility),
  "notifications": [
    enum (NotificationType)
  ],
  "planInfoPerClient": {
    object (PlanInfoPerClient)
  },
  "cpidState": enum (CpidState)
}
欄位
name

string

PlanStatus 的資源名稱，格式如下：operators/{asn_id}/planStatuses/{userKey}。建立 PlanStatus 項目時，系統會忽略這個名稱。
plans[]

object (Plan)

這位使用者擁有的方案清單。
languageCode

string

必要，BCP-47 語言代碼，例如「en-US」或「sr-Latn」。詳情請參閱 http://www.unicode.org/reports/tr35/#Unicode_locale_identifier。
expireTime

string (Timestamp format)

必要，共用企劃書群組資訊過時的時間。這段期間過後，應用程式就不會提供 PlanStatus。到期時間必須在未來。

RFC3339 UTC 的「Zulu」格式時間戳記，單位為奈秒解析度，最多可達九位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
updateTime

string (Timestamp format)

必要，數據方案代理程式 (DPA) 從後端系統擷取方案狀態資訊的時間。可用來判斷方案狀態資訊的近期日期。更新時間必須是過去的時間，但不得超過 30 天。

RFC3339 UTC 的「Zulu」格式時間戳記，單位為奈秒解析度，最多可達九位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
title

string

使用者與電信業者的合約名稱。這會顯示在使用者介面標頭中。
subscriberId

string

電信業者系統中的不重複穩定 ID，用於識別使用者。
accountInfo

object (AccountInfo)

僅適用於預付使用者。使用者帳戶餘額的相關資訊。
uiCompatibility

enum (UiCompatibility)

決定是否要在使用者介面向使用者顯示 PlanStatus。設為 UI_INCOMPATIBLE 時，PlanStatus 可用來傳送通知，不會向使用者顯示企劃書資訊。
notifications[]

enum (NotificationType)

包含 GTAF 傳送給使用者的通知類型清單。如果呼叫者填入這個欄位，GTAF 就會忽略這個欄位。
planInfoPerClient

object (PlanInfoPerClient)

與特定 Google 客戶相關的數據方案資訊。
cpidState

enum (CpidState)

與這個企劃書狀態相關聯的 CPID 狀態。

方案

使用者的行動資費方案，其中包含訂閱者購買的頂層行動服務方案。方案可以簡單來說為「10 GB 的 30 天行動數據」；也可以定義為一組元件 (稱為方案模組)。例如，ACME 方案 199，描述為「2GB 資料」、「無限制的 WhatsApp + 無限即時通訊和 1 GB Spotify」，包含三個方案模組。

JSON 表示法 
{
  "planName": string,
  "planId": string,
  "planCategory": enum (PlanCategory),
  "expirationTime": string,
  "planModules": [
    {
      object (PlanModule)
    }
  ],
  "planState": enum (PlanState)
}
欄位
planName

string

使用者的行動方案名稱，
planId

string

必要，方案 ID，用於在優惠期間參照方案等。
planCategory

enum (PlanCategory)

預付或後付方案。
expirationTime

string (Timestamp format)

必要，方案到期後。對於大多數方案，這個時間長度應等於所有方案模組專屬到期時間的最大值。對於會定期重新整理模組配額的方案，這應為整體方案到期時間，也就是方案模組停止重新整理的時間。如果方案未過期，則可略過這個欄位。

RFC3339 UTC 的「Zulu」格式時間戳記，單位為奈秒解析度，最多可達九位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
planModules[]

object (PlanModule)

詳細方案模組 (子方案) 資訊。
planState

enum (PlanState)

使用者方案的狀態，例如有效、無效。

方案類別

可能的企劃書類別類型。

列舉
PLAN_CATEGORY_UNSPECIFIED 未指明
PREPAID 預付方案。
POSTPAID 後付方案，

規劃模組

方案中每個數據方案模組 (或子方案) 的資訊。

JSON 表示法 
{
  "coarseBalanceLevel": enum (BalanceLevel),
  "trafficCategories": [
    enum (PlanModuleTrafficCategory)
  ],
  "expirationTime": string,
  "overUsagePolicy": enum (OverUsagePolicy),
  "maxRateKbps": string,
  "description": string,
  "moduleName": string,
  "usedBytes": string,
  "planModuleState": enum (PlanState),
  "refreshPeriod": enum (RefreshPeriod),

  // Union field balance can be only one of the following:
  "byteBalance": {
    object (ByteQuota)
  },
  "timeBalance": {
    object (TimeQuota)
  }
  // End of list of possible types for union field balance.
}
欄位
coarseBalanceLevel

enum (BalanceLevel)

粗略餘額資訊。
trafficCategories[]

enum (PlanModuleTrafficCategory)

系統將根據這個企劃書模組計費的流量類別清單。
expirationTime

string (Timestamp format)

必要，方案模組的特定到期時間。如果是會定期重新整理配額的企劃書模組，這是指下次更新模組的時間。如果方案模組並無任何到期時間，則可略過這個欄位。

RFC3339 UTC 的「Zulu」格式時間戳記，單位為奈秒解析度，最多可達九位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
overUsagePolicy

enum (OverUsagePolicy)

超額使用政策，例如節流。
maxRateKbps

string (int64 format)

這個方案模組允許的資料速率上限 (Kbps)。視網路狀況而定，觀察到的實際資料速率介於 0 和 maxRateKbps 之間。如果省略 maxRateKbps 或設為 0，則表示不要對這個方案模組執行節流。
description

string

必要，方案模組的說明可能會向使用者顯示，因此應接近企劃書模組的市場說明。
moduleName

string

必要，方案模組的名稱。
usedBytes

string (int64 format)

使用者使用這個方案模組的位元組數。
planModuleState

enum (PlanState)

企劃書模組的狀態，例如「有效」、「無效」
refreshPeriod

enum (RefreshPeriod)

這個方案模組的重新整理週期，如果方案模組未重新整理配額，則傳回 REFRESH_PERIOD_NONE。重新整理配額的計畫模組會在每次重新整理週期執行一次。
聯集欄位 balance。必要，方案模組餘額資訊，應為下列其中一種：bytes_balance、time_balance、coarse_balance_level。balance 只能是下列其中一項：
byteBalance

object (ByteQuota)

以位元組為單位的計畫模組餘額資訊。對於定期重新整理的模組，這個欄位代表每個重新整理週期的位元組餘額。
timeBalance

object (TimeQuota)

以時間為準的企劃書模組餘額資訊。針對定期重新整理的模組，這個欄位會表示每次重新整理的時間範圍。

位元組配額

以位元組為單位的計畫模組配額/餘額資訊。

JSON 表示法 
{
  "quotaBytes": string,
  "remainingBytes": string
}
欄位
quotaBytes

string (int64 format)

模組配額 (以位元組為單位)。如果是無限方案，應設為 2^63 - 1 (9223372036854775807)。
remainingBytes

string (int64 format)

適用於低餘額通知。剩餘配額餘額 (以位元組為單位)。

時間配額

以時間為基礎的方案模組配額/餘額資訊。

JSON 表示法 
{
  "quotaMinutes": string,
  "remainingMinutes": string
}
欄位
quotaMinutes

string (int64 format)

以時間為準的模組中的模組配額，例如180 分鐘。
remainingMinutes

string (int64 format)

以時間為基礎的方案剩餘的配額餘額，例如40 分鐘。

餘額等級

概略方案模組資料餘額資訊。

列舉
BALANCE_LEVEL_UNSPECIFIED 未指明
NO_PLAN 無數據方案。
OUT_OF_DATA 資料餘額為零。
LOW_QUOTA 資料餘額 (或剩餘時間) 等於或小於原始資產包餘額 (或時間) 的 10-25%。貨運公司可能會視情況決定每個包裹的確切門檻。
HIGH_QUOTA 資料餘額 (或剩餘時間) 超過原始組合餘額 (或時間) 的 10-25%。貨運公司可能會視情況決定每個包裹的確切門檻。資料餘額偏高。

企劃書模組流量類別

方案模組流量類別，說明特定方案模組中的應用程式流量組合。

列舉
PLAN_MODULE_TRAFFIC_CATEGORY_UNSPECIFIED 未指明
GENERIC 一般流量，適用於所有流量。
VIDEO 所有影片流量。
VIDEO_BROWSING 影片探索 (瀏覽) 流量，也就是所有影片應用程式流量 (影片/音訊串流部分除外)。
VIDEO_OFFLINE 影片離線流量，也就是 VIDEO_BROWSING 和離線/非串流 (非串流) 流量的總和。
MUSIC 音樂應用程式流量。
GAMING 遊戲應用程式流量。
SOCIAL 社交應用程式流量。
MESSAGING 訊息應用程式流量。
APP_STORE 應用程式商店流量，例如更新或下載新的應用程式。

過度使用政策

超過用量政策：使用者配額用盡時的情形。

列舉
OVER_USAGE_POLICY_UNSPECIFIED 未指明
THROTTLED 速度受到限制。
BLOCKED 連線已遭封鎖。
PAY_AS_YOU_GO 即付即用，以量計費。

企劃書狀態

列舉各種使用者方案/方案模組的狀態。

列舉
ACTIVE 企劃書/PlanModule 有效，使用者可以使用模組提供的資料。
INACTIVE 「方案/企劃書」模組無效，雖然使用者仍具備該模組，但使用者無法使用模組中的資料。如果模組只在一天中的特定時段提供資料，或是使用者已購買模組，但尚未啟用，就有可能會發生這種情況。
EXPIRING_SOON Plan/PlanModule 即將到期。呼叫端應選擇適當層級，決定設定這個值的時機。這代表已生效。
NEWLY_ACTIVE 先前已啟用或不存在的 Planning/PlanModule。此狀態只應在啟用時間後的極短時間內使用，否則應改用「ACTIVE 狀態」。使用 NEWLY_ACTIVE 模組傳送數據方案狀態通知時，應使用短期 TTL，因為 NEWLY_ACTIVE 狀態很快會變得準確。
EXPIRED Plan/PlanModule 已過期。設定這個列舉值會觸發方案過期的通知。

重新整理週期

代表重新整理週期，也就是重設企劃書模組的固定間隔。

列舉
REFRESH_PERIOD_NONE 沒有重新整理週期。如果方案模組並非週期性，應使用這個選項。
DAILY 方案模組每天都會重設。
MONTHLY 這個方案模組會每月重設一次。
BIWEEKLY 計劃模組每兩週重設一次。
WEEKLY 這個方案模組每週都會重設。

AccountInfo

預付使用者的帳戶餘額資訊。

JSON 表示法 
{
  "accountBalance": {
    object (Money)
  },
  "loanBalance": {
    object (Money)
  },
  "unpaidLoan": {
    object (Money)
  },
  "accountBalanceStatus": enum (AccountBalanceStatus),
  "validUntil": string,
  "payAsYouGoCharge": {
    object (Money)
  },
  "accountTopUp": {
    object (Money)
  }
}
欄位
accountBalance

object (Money)

必要，使用者帳戶的帳戶餘額。
loanBalance

object (Money)

必要項目。用電信業者的貸款儲值後的使用者帳戶餘額。如果有的話，帳戶 accountBalance 不會包含此餘額。
unpaidLoan

object (Money)

使用者因電信業者貸款而積欠電信業者的金額。
accountBalanceStatus

enum (AccountBalanceStatus)

必要，表示帳戶餘額。如果 validUntil 時間與 accountBalanceStatus 欄位不符，我們會使用 accountBalanceStatus。
validUntil

string (Timestamp format)

必要，帳戶餘額的有效期間。這個欄位會用來向顯示剩餘帳戶餘額，

RFC3339 UTC 的「Zulu」格式時間戳記，單位為奈秒解析度，最多可達九位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。
payAsYouGoCharge

object (Money)

使用者採用「即付即用」方案時，使用者花費的金額。如果電信業者在與 GTAF 分享帳戶資訊時填入這個欄位，GTAF 就會嘗試傳送通知給使用者，表示他們會在即付即用狀態下支出資金。
accountTopUp

object (Money)

帳戶儲值通知需要。使用者儲值至帳戶餘額的金額。如果電信業者在與 GTAF 分享帳戶資訊時填入這個欄位，GTAF 會嘗試傳送通知，向使用者指出帳戶已儲值。

金額

代表金額與其貨幣類型。

JSON 表示法 
{
  "currencyCode": string,
  "units": string,
  "nanos": integer
}
欄位
currencyCode

string

由 ISO 4217 定義的 3 個字母貨幣代碼。
units

string (int64 format)

總金額。舉例來說，如果 currencyCode 為 "USD"，則 1 單位為美元。
nanos

integer

金額的奈米 (10^-9) 單位數量。這個值必須介於 -999,999,999 和 +999,999,999 (含) 之間。如果 units 為正數，則 nanos 必須為正數或零。如果 units 為零，nanos 可以是正數、零或負值。如果 units 為負值，nanos 必須是負值或零。舉例來說，$-1.75 會顯示為 units=-1，nanos=-750,000,000。

帳戶餘額

使用者錢包的狀態。

列舉
VALID 使用者帳戶餘額有效，可用於購買交易。
INVALID 使用者帳戶餘額無效，且您必須在未進行變更的情況下才能使用。

Ui 相容性

用來表示能否向使用者顯示共用 Planning 狀態的列舉。

列舉
UI_COMPATIBILITY_UNSPECIFIED 根據預設，我們會假設 PlanStatus 與 UI 相容。
UI_COMPATIBLE 表示整個 PlanStatus 與 UI 相容，且系統會向使用者顯示方案資訊。
UI_INCOMPATIBLE 表示 PlanStatus 不與 UI 相容。欄位可用來傳送通知給使用者，但不能用來向使用者顯示方案資訊。

通知類型

傳送給行動數據方案設定的通知類型。

列舉
NOTIFICATION_UNDEFINED 不明的通知類型
NOTIFICATION_LOW_BALANCE_WARNING 警告使用者餘額偏低的通知
NOTIFICATION_DATA_EXPIRATION_WARNING 向使用者提醒數據方案即將過期的通知
NOTIFICATION_OUT_OF_DATA 使用者資料用盡的通知
NOTIFICATION_PLAN_ACTIVATION 使用者購買方案現已生效的通知
NOTIFICATION_PAY_AS_YOU_GO 通知使用者配合即付即用的狀態，使用者需要支付資料費用。
NOTIFICATION_ACCOUNT_TOP_UP 通知使用者，說明帳戶餘額已儲值。
NOTIFICATION_DATA_EXPIRED 通知使用者他們的數據方案已過期。

方案個別用戶端

與特定 Google 客戶相關的數據方案資訊。

JSON 表示法 
{
  "youtube": {
    object (YouTube)
  },
  "androidSystemInfo": {
    object (AndroidSystemInfo)
  }
}
欄位
youtube

object (YouTube)

YouTube 相關方案的資訊。
androidSystemInfo

object (AndroidSystemInfo)

Android 系統相關資訊。

YouTube

YouTube 相關數據方案資訊。

JSON 表示法 
{
  "rateLimitedStreaming": {
    object (RateLimitedStreaming)
  }
}
欄位
rateLimitedStreaming

object (RateLimitedStreaming)

YouTube Plan Aware Streaming (PAS) 功能，限制影片的放送位元率。

RateLimitedStreaming

數據方案資訊，用於協助 YouTube 改善頻率限制的串流使用者體驗。

JSON 表示法 
{
  "maxMediaRateKbps": integer
}
欄位
maxMediaRateKbps

integer

這位使用者支援的 YouTube 位元率 (kbps (每秒 1000 和 39 個位元)。

Android 系統資訊

與整個 Android 系統相關的數據方案資訊。

JSON 表示法 
{
  "cellularInfo": [
    {
      object (CellularInfo)
    }
  ]
}
欄位
cellularInfo[]

object (CellularInfo)

每種連線類型的行動資訊。例如，每種連線類型 (例如 4G、5G 都有) 會有一則 mobileInfo 訊息。

行動網路資訊

方案為使用者提供行動網路連線的相關資訊。

JSON 表示法 
{
  "connectionType": enum (ConnectionType),
  "meteredness": enum (Meteredness)
}
欄位
connectionType

enum (ConnectionType)

運算子提供給使用者的連線類型。
meteredness

enum (Meteredness)

使用者方案的計量付費狀態。

ConnectionType

連線類型：2G、3G、4G

列舉
CONNECTION_TYPE_UNSPECIFIED 未指明
CONNECTION_2_G 2G：
CONNECTION_3_G 3G。
CONNECTION_4_G 4G。
CONNECTION_5_G 5G。
CONNECTION_ALL 所有音樂。

計量付費

使用者擁有的方案類型

列舉
METEREDNESS_UNSPECIFIED GTAF 不知道使用者方案的計量付費狀態。
METEREDNESS_UNMETERED 使用者採用非計量付費方案。
METEREDNESS_METERED 使用者採用計量付費方案。

CpidState

表示電信業者的列舉，用來表示 CPID 狀態。

列舉
CPID_STATE_UNSPECIFIED CPID 的狀態不明。系統會將此視為 CPID 有效。
CPID_INVALIDATED CPID 無效，用戶端應從 CPID 端點擷取新的 CPID。

方法

create

 允許行動電信業者 (透過專屬自治系統號碼 (ASN) 辨識) 新增 PlanStatus 項目，供特定用戶端使用。