REST Resource: projects.locations.privateOffers

資源：PrivateOffer

說明 PrivateOffer 資源的訊息。

選填欄位注意事項：為方便儲存未完成的草擬方案，無論私人方案是否需要這些欄位，大多數欄位都會歸類為選填。如要發布優惠，必須設定許多標示為「選填」的欄位。

JSON 表示法 
{
  "name": string,
  "state": enum (State),
  "publishRequirementGoogleReview": {
    object (PublishRequirementGoogleReview)
  },
  "createTime": string,
  "updateTime": string,
  "publishTime": string,
  "acceptTime": string,
  "cancelTime": string,
  "endTime": string,
  "cancellationNote": string,
  "resellerContact": {
    object (ResellerContact)
  },
  "internalNote": string,
  "offerDealType": enum (OfferDealType),
  "title": string,
  "customerNote": string,
  "partnerContact": {
    object (PartnerContact)
  },
  "customer": {
    object (Customer)
  },
  "acceptDeadlineTime": {
    object (DateTime)
  },
  "term": {
    object (Term)
  },

  // Union field content can be only one of the following:
  "singleProductOffer": {
    object (SingleProductOffer)
  }
  // End of list of possible types for union field content.
}
欄位
name

string

ID。資源名稱。
state

enum (State)

僅供輸出。私密優惠的狀態。
publishRequirementGoogleReview

object (PublishRequirementGoogleReview)

僅供輸出。Google 審查程序的相關資訊。只有在 Google 判定優惠需要審查時，才會顯示這項訊息。
createTime

string (Timestamp format)

僅供輸出。建立時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
updateTime

string (Timestamp format)

僅供輸出。上次更新時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
publishTime

string (Timestamp format)

僅供輸出。提案轉換為「已發布」狀態的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
acceptTime

string (Timestamp format)

僅供輸出。提案轉換為「已接受」狀態的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
cancelTime

string (Timestamp format)

僅供輸出。優惠轉換為 CANCELLED 狀態的時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
endTime

string (Timestamp format)

僅供輸出。優惠結束時間。只有 ENDED 狀態的優惠才能設定這項屬性。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。
cancellationNote

string

僅供輸出。取消優惠時提供的內部附註。僅適用於已取消的優惠，且僅在提供附註時顯示。
resellerContact

object (ResellerContact)

僅供輸出。經銷商聯絡人資訊。僅適用於經銷商建立的方案。
internalNote

string

選用。顧客看不到的非結構化文字內容。合作夥伴可使用這個欄位儲存私密優惠的附註。長度上限：1500 個半形字元。
offerDealType

enum (OfferDealType)

選用。透過優惠進行交易的交易類型。

顧客不會看到特惠類型。

必須在場才能發布優惠。
title

string

選用。說明優惠內容的標題，有助於顧客辨識優惠。顧客會看到這個標題。長度上限為 256 個半形字元。必須在場才能發布優惠。
customerNote

string

選用。顧客可見的非結構化文字內容。長度上限：120 個半形字元。
partnerContact

object (PartnerContact)

選用。合作夥伴聯絡人資訊。發布優惠時必須提供這項資訊。
customer

object (Customer)

選用。識別優惠適用對象的資訊。發布優惠時必須提供這項資訊。
acceptDeadlineTime

object (DateTime)

選用。已發布優惠的接受期限。如果發布的優惠未在期限內接受，就會過期。系統僅支援 America/Los_Angeles 時區的日期界線。必須在場才能發布優惠。

發布優惠時，截止日期必須設為未來時間，且不得超過發布時間起算的 3 個月。舉例來說，如果優惠在 5 月 3 日下午 1 點發布，則截止日期必須在 5 月 6 日凌晨 12 點 (美洲/洛杉磯時間) 之前。

截止日期也必須符合下列條件：

  • 早於或等於這項優惠的排定開始時間 (如果已設定 term.scheduled_start_time，且該項目的開始政策為 SCHEDULED_START_TIME)。
  • 如果已設定 term.scheduled_end_time，且條款的結束政策為 SCHEDULED_END_TIME，則必須在優惠排定的結束時間之前或當天。
  • 不得晚於這項優惠的下期付款開始時間。
  • 如果優惠是修改其他私密或標準優惠，則必須在修改後優惠的結束時間之前或當天。
  • 如果修改的私密優惠包含自訂分期付款，則必須在下一個待處理分期付款的開始時間之前或當天完成。舉例來說，如果修訂後的方案在 1 月 1 日、2 月 1 日、3 月 1 日、4 月 1 日有分期付款，而今天是 2 月 15 日，則這項方案的 acceptDeadlineTime 必須在 3 月 1 日或之前。

此外，如果這項優惠是修改其他私密優惠，但該私密優惠已接受即將生效的修改，則這項優惠的接受期限必須早於或等於已接受即將生效優惠的開始時間。舉例來說，今天是 2 月 15 日，這項優惠 (優惠 C) 是私密優惠 A 的修訂版本，而私密優惠 B 也已接受，同樣是私密優惠 A 的修訂版本。私密優惠 B 的開始時間為 3 月 1 日。那麼這個期限必須在 3 月 1 日當天或之前。否則，私密優惠 B 會在 3 月 1 日生效，取代優惠 A。這表示優惠 C 不再是目前有效優惠 (優惠 A) 的修訂版本，而修訂版本必須是目前有效優惠的修訂版本。

發布後，您仍可更新這個欄位，延長優惠期限。不過，延期後的期限仍不得超過發布時間起算的 3 個月。
term

object (Term)

選用。優惠條款的設定。發布優惠時必須設定。
聯集欄位 content。優惠內容。日後可能會支援其他形式的內容。如要發布優惠，必須提供內容值。content 只能是下列其中一個設定：
singleProductOffer

object (SingleProductOffer)

選用。與單一產品相關聯的優惠設定。

SingleProductOffer

與單一產品相關聯的優惠設定。

JSON 表示法 
{
  "baseStandardOffer": string,
  "serviceLevel": string,
  "resellerPrivateOfferPlanId": string,
  "features": [
    {
      object (Feature)
    }
  ],
  "effectiveInstallmentTimeline": [
    {
      object (Installment)
    }
  ],
  "contractValue": {
    object (ContractValue)
  },
  "revenueShare": {
    object (RevenueShare)
  },

  // Union field amended_offer can be only one of the following:
  "amendedPrivateOffer": string,
  "amendedStandardOffer": string
  // End of list of possible types for union field amended_offer.

  // Union field price can be only one of the following:
  "standardIntervalPrice": {
    object (StandardIntervalPrice)
  },
  "customIntervalPrice": {
    object (CustomIntervalPrice)
  }
  // End of list of possible types for union field price.
}
欄位
baseStandardOffer

string

選用。這個 PrivateOffer 所依據的 StandardOffer。必須與私密優惠位於相同專案，且發布時必須有效。必須在場才能發布優惠。

格式：projects/{project}/locations/{location}/services/{service}/standardOffers/{standard_offer}
serviceLevel

string

僅供輸出。基本標準方案的服務等級 (又稱「方案」)。發布時，系統會從基本標準方案填入值。
resellerPrivateOfferPlanId

string

僅供輸出。適用於經銷商根據經銷商私密優惠方案 (RPOP) 建立的優惠。設定後，會包含原始 RPOP 的 ID。不適用於 PRIVATE_OFFER_VIEW_BASIC。
features[]

object (Feature)

選用。這項優惠要顯示的自訂產品功能。如要發布優惠，功能 displayName 值不得重複。這裡指定的功能組合一般應包含基本服務等級的所有功能，並可選擇自訂值，但不一定要完全相符，且可能包含額外功能。
effectiveInstallmentTimeline[]

object (Installment)

僅供輸出。優惠的有效分期付款時間表。不適用於 PRIVATE_OFFER_VIEW_BASIC。如果所有必要資訊都已備妥，可產生時間軸，且方案的「standardIntervalPrice」為「MONTHLY_PRORATED」、「MONTHLY_NOT_PRORATED」、「QUARTERLY_NOT_PRORATED」或「YEARLY_NOT_PRORATED」，則會包含 PRIVATE_OFFER_VIEW_FULL。
contractValue

object (ContractValue)

僅供輸出。優惠的合約價值。不適用於 PRIVATE_OFFER_VIEW_BASIC。
revenueShare

object (RevenueShare)

僅供輸出。這項私密優惠的收益分潤資訊。不適用於 PRIVATE_OFFER_VIEW_BASIC。
聯集欄位 amended_offer。這項私密優惠將取代的現有優惠。amended_offer 只能是下列其中一個設定：
amendedPrivateOffer

string

選用。這項優惠將取代現有的私密優惠。除非私密優惠適用於支援多筆有效訂單的產品類型，否則只有在目標客戶帳單帳戶已包含相同產品的有效訂單時，才能交易修訂私密優惠。要取代的方案必須是與有效訂單相關聯的方案。

修正內容通常屬於下列其中一種情況：

  1. 有效訂單 / 已結束的優惠：經過修改的優惠已結束，但仍與有效訂單相關聯。新方案必須修改已結束的私密優惠。
  2. 有效訂單 / 有效優惠：修改後的優惠條款仍有效，且相關訂單有效。與上述情況類似，新優惠必須修改目前有效優惠 (除非支援「多個有效訂單」)。

如果設定這個項目，則 baseStandardOffer 父項服務必須與 amendedPrivateOffer 中 baseStandardOffer 的父項服務相符。

有效期限限制：如果修訂後的私密優惠期限尚未結束，則適用下列相容性規則：

  • 價格模式相容性：
    • 固定費率 (含或不含用量) 優惠可以修改固定費率優惠。
    • 僅限用量或 CUD 方案可修改僅限用量方案。
    • 承諾型方案必須修改相同價格模式子類型的方案 (例如「額外用量依定價計算」與「所有用量均享折扣」)。
  • 帳單週期相容性：由 standardInterval 或 customIntervalPrice 決定。
    • 如果修訂後的方案採用自訂帳單結算頻率，新方案也必須採用自訂頻率。
    • 如果修訂後的方案採用標準頻率 (每月、每季或每年)，新方案必須維持相同頻率，或改為自訂頻率。
    • 系統不支援在不同標準頻率之間切換 (例如從每月切換為每季)。
    • 如果是每月頻率，除非方案的 term.end_policy為 MATCH_AMENDED_OFFER，否則系統支援在 MONTHLY_PRORATED 和 MONTHLY_NOT_PRORATED 之間切換。
    • 如果是僅限用量的方案，則沒有帳單週期限制。

如需其他優惠修訂條件，請參閱其他文章。
amendedStandardOffer

string

選用。現有的標準優惠，將由這項優惠取代。如果目標客戶帳單帳戶已包含相同產品的有效訂單，就必須交易修訂內容私密優惠，否則無法交易。要取代的優惠必須與有效訂單相關聯。

如果設定這個項目，則 baseStandardOffer 必須包含與 amendedStandardOffer 上層服務相同的上層服務。這項方案的價格模式必須與 amendedStandardOffer 的價格模式相容：

  • 固定費率或固定費率 (含用量) 優惠可修改固定費率或固定費率 (含用量) 標準優惠。
  • 僅限用量優惠或 CUD 優惠可修改僅限用量的標準優惠。

如需其他優惠修訂條件，請參閱其他文章。
聯集欄位 price。優惠價格。發布優惠時必須設定價格。price 只能是下列其中一個設定：
standardIntervalPrice

object (StandardIntervalPrice)

選用。提供標準間隔的方案價格設定。發布優惠時必須設定價格。
customIntervalPrice

object (CustomIntervalPrice)

選用。提供自訂間隔的優惠價格設定。自訂間隔對應「自訂帳單結算頻率」，請參閱 https://docs.cloud.google.com/marketplace/docs/partners/offers/select-payment-schedule。發布優惠時必須設定價格。

StandardIntervalPrice

提供標準間隔的方案價格設定。

JSON 表示法 
{
  "standardInterval": enum (StandardInterval),
  "priceModel": {
    object (PriceModel)
  }
}
欄位
standardInterval

enum (StandardInterval)

選用。優惠的標準間隔。除非計價模式僅限用量，否則必須提供這項屬性才能發布。
priceModel

object (PriceModel)

選用。優惠的價格模式。必須在場才能發布優惠。

StandardInterval

提供標準間隔的方案選項。

列舉
STANDARD_INTERVAL_UNSPECIFIED 私密優惠沒有間隔。如果設定了這項屬性，則優惠為「僅限使用」。「欄位」term.duration_months必須為正數。
MONTHLY_POSTPAY

每月後付型方案優惠的排程。這類方案的帳單結算頻率為「每月」(請參閱 https://docs.cloud.google.com/marketplace/docs/partners/offers/select-payment-schedule)。我們已在 2024 年 5 月停止支援這個屬性。無法用於發布新優惠。
MONTHLY_PRORATED

按月分期付款 (按比例計算)。這類方案的帳單結算頻率為「每月」(請參閱 https://docs.cloud.google.com/marketplace/docs/partners/offers/select-payment-schedule)。舉例來說，如果優惠開始日期為 4 月 15 日，優惠期間為 3 個月，系統會建立下列分期付款：

所有日期均代表 America/Los_Angeles 時區當天的開始時間。

如果已設定：

  • 必須設定 PriceModel.subscription oneof。
  • 「欄位」term.duration_months必須為正數。
MONTHLY_NOT_PRORATED

按月分期付款，不按比例計算。這類方案的帳單結算頻率為「每月」(請參閱 https://docs.cloud.google.com/marketplace/docs/partners/offers/select-payment-schedule)。舉例來說，如果優惠開始日期為 4 月 15 日，優惠期間為 3 個月，系統會建立下列分期付款：

所有日期均代表 America/Los_Angeles 時區當天的開始時間。

如果已設定：

  • 必須設定 PriceModel.subscription oneof。
  • 「欄位」term.duration_months必須為正數。
QUARTERLY_NOT_PRORATED

每季分期付款，不按比例計算。這類方案的帳單結算頻率為「每季」(請參閱 https://docs.cloud.google.com/marketplace/docs/partners/offers/select-payment-schedule)。舉例來說，如果優惠於 1 月 15 日開始，且優惠期間為 3 季，系統會建立下列分期付款：

所有日期均代表 America/Los_Angeles 時區當天的開始時間。

如果已設定：

  • 必須設定 PriceModel.subscription oneof。
  • 「欄位」term.duration_months必須為正數。
YEARLY_NOT_PRORATED

年度分期付款，不會按比例計算。這類方案的帳單結算頻率為「每年」(請參閱 https://docs.cloud.google.com/marketplace/docs/partners/offers/select-payment-schedule)。舉例來說，如果優惠開始日期為 2025 年 1 月 15 日，優惠期限為 3 年，系統會建立下列分期付款：

所有日期均代表 America/Los_Angeles 時區當天的開始時間。

如果已設定：

  • 必須設定 PriceModel.subscription oneof。
  • 「欄位」term.duration_months必須為正數。

PriceModel

私密優惠的價格模式。

私有方案的價格模式會因價格模式中設定的欄位組合而異。說明文件和其他參考資料會使用下列術語。

  • 按用量計費：定價模式未設定 flatFee
  • 僅限用量：定價模式只會設定 usage
  • CUD (承諾使用折扣)：價格模式會設定 commitment
    • 額外用量依定價計算的承諾使用折扣：價格模式會設定 commitment，而非 usage。
    • 所有用量都享有折扣的承諾使用合約：定價模式會設定 commitment 和 usage。
  • 固定費用：定價模式只會設定 flatFee
  • 固定費用與用量費用：價格模式會設定 flatFee 和 usage

如需價格模式，請參閱 https://docs.cloud.google.com/marketplace/docs/partners/offers/select-pricing-model#CUD。

JSON 表示法 
{
  "usage": {
    object (Usage)
  },

  // Union field subscription can be only one of the following:
  "flatFee": {
    object (FlatFee)
  },
  "commitment": {
    object (Commitment)
  }
  // End of list of possible types for union field subscription.
}
欄位
usage

object (Usage)

選用。用量部分的價格設定。如果設定這個欄位，就必須取消設定 Commitment.discount_percent。私人方案可為所有用量或承諾用量套用折扣，但不能同時套用。如果基本標準方案的價格模式不含用量 SKU，則必須取消設定。
聯集欄位 subscription。訂閱部分的價格設定。subscription 只能是下列其中一個設定：
flatFee

object (FlatFee)

選用。固定費用方案的價格設定。如果基本標準方案的價格模式不含訂閱 SKU，則必須取消設定。
commitment

object (Commitment)

選用。承諾使用合約訂閱方案的價格設定。如果基本標準方案的價格模式包含訂閱 SKU，則必須取消設定。

FlatFee

固定費用訂閱方案的價格設定。

JSON 表示法 
{
  "flatFeeOverride": {
    object (Money)
  }
}
欄位
flatFeeOverride

object (Money)

選用。固定費用會覆寫基本標準方案中的預設固定費用。值不得為負數。幣別必須為「USD」，且精確度僅限於美分。如果已設定父項訊息，則必須提供這項屬性才能發布優惠。允許的最大值為 1,000,000,000 美元。

承諾使用合約

承諾使用合約訂閱方案的價格設定。

JSON 表示法 
{
  "commitmentAmount": {
    object (Money)
  },
  "discountPercent": {
    object (Decimal)
  },
  "additionalCredit": {
    object (Money)
  },
  "discardPreviousCreditBalance": boolean
}
欄位
commitmentAmount

object (Money)

選用。客戶可獲得的承諾使用餘額，值不得為負數。幣別必須為「USD」，且精確度僅限於美分。如果已設定父項訊息，則必須提供這項屬性才能發布優惠。允許的最大值為 1,000,000,000 美元。

如果目前的優惠修訂了尚未到期的私密優惠，且目前優惠和修訂後的私密優惠都設定了 singleProductOffer.standard_interval_price.price_model.commitment.commitment_amount 欄位，則目前優惠的承諾金額必須等於或高於修訂後的私密優惠。
discountPercent

object (Decimal)

選用。commitmentAmount的折扣百分比。

舉例來說，10 表示折扣 10%。如果原始 commitmentAmount 為 $100 美元，折扣金額則為 $90 美元。客戶支付 $90 美元，並獲得 $100 美元抵免額。

所有回報的用量都會按標準價格計費。如果設定這個欄位，就必須取消設定 priceModel.usage。私人方案可為所有用量或承諾用量套用折扣，但不能同時套用。

必須介於 0 到 100 之間，最多可到小數點後第二位。如果設定了這個欄位，則「值」的允許模式為 ^([0-9]{1,2}(\\.\\d{1,2})?|100(\\.0{1,2})?)$。有效值範例：「0」、「100.0」、「12.34」、「40.0」。無效值範例：「.3」、「-1」、「100.1」、「12.345」、「+12」、「」。

必須在場才能發布優惠。
additionalCredit

object (Money)

選用。提供客戶額外的抵免額。額外抵免額僅適用於自訂間隔優惠。如要為標準間隔優惠達到相同效果，請變更 commitmentAmount 和 discountPercent。

值不得為負數。幣別必須為「USD」，且精確度僅限於美分。允許的最大值為 1,000,000 美元。
discardPreviousCreditBalance

boolean

選用。是否要在相關分期付款開始時，捨棄先前的信用額度餘額。如未設定，系統會將先前的抵免額餘額轉移至當期付款。

如果沒有先前的分期付款，這個欄位的值就不重要，因為沒有抵免額時，這個欄位不會有任何作用。

用量

使用 SKU 的價格。

JSON 表示法 
{
  "defaultDiscountPercent": {
    object (Decimal)
  },
  "skuDiscounts": [
    {
      object (SkuDiscount)
    }
  ]
}
欄位
defaultDiscountPercent

object (Decimal)

選用。用量 SKU 的預設折扣百分比。如果未設定預設折扣百分比，系統會視為 0 (無折扣)。

必須介於 0 到 100 之間，最多可到小數點後第二位。如果設定了這個欄位，則「值」的允許模式為 ^([0-9]{1,2}(\\.\\d{1,2})?|100(\\.0{1,2})?)$。有效值範例：「0」、「100.0」、「12.34」、「40.0」。無效值範例：「.3」、「-1」、「100.1」、「12.345」、「+12」、「」。
skuDiscounts[]

object (SkuDiscount)

選用。特定 SKU 的折扣，會覆寫 defaultDiscountPercent。

SkuDiscount

特定 SKU 的折扣。

JSON 表示法 
{

  // Union field target can be only one of the following:
  "sku": string,
  "cloudBillingSku": string
  // End of list of possible types for union field target.

  // Union field discount can be only one of the following:
  "discountPercent": {
    object (Decimal)
  }
  // End of list of possible types for union field discount.
}
欄位
聯集欄位 target。這是必要旗標，折扣適用的 SKU。target 只能是下列其中一個設定：
sku

string

選用。這個 API 中的合作夥伴 SKU 名稱。

必須參照基本標準方案價格模式中的 SKU。基本價格模式可直接或間接納入，也就是納入隨附的 SkuGroup。

目前標準方案價格模式僅包含與標準方案位於同一專案的合作夥伴 SKU。這項資訊可能會變更。

格式：projects/{project}/locations/{location}/services/{service}/skus/{sku}
cloudBillingSku

string

選用。Cloud Billing API 中的 Google SKU 名稱。

用於 Google 銷售的合作夥伴產品，例如在 Compute Engine 中使用的付費作業系統映像檔。這種情況並不常見。這類 SKU 不會出現在這個 API 中，而是會顯示在 Cloud Billing API 或 https://cloud.google.com/skus。

必須參照基本標準方案價格模式中的 SKU。標準方案一律會透過 SkuGroups 參照 Google SKU。

格式：services/{service}/skus/{sku}
聯集欄位 discount。SKU 的折扣。discount 只能是下列其中一個設定：
discountPercent

object (Decimal)

選用。SKU 的折扣百分比。舉例來說，10 表示折扣 10%。如果原始 SKU 價格為每小時 $100 美元，折扣價則為每小時 $90 美元。

必須介於 0 到 100 之間，最多可到小數點後第二位。如果設定了這個欄位，則「值」的允許模式為 ^([0-9]{1,2}(\\.\\d{1,2})?|100(\\.0{1,2})?)$。

有效值範例：「0」、「100.0」、「12.34」、「40.0」。無效值範例：「.3」、「-1」、「100.1」、「12.345」、「+12」和「」。必須提供此值才能發布優惠。

CustomIntervalPrice

提供自訂間隔的優惠價格設定。

JSON 表示法 
{
  "installments": [
    {
      object (Installment)
    }
  ]
}
欄位
installments[]

object (Installment)

選用。構成分期付款排程的分期付款。所有期數都必須採用相同的價格模式 (例如全為承諾用量，或全為固定費用)。每個分期付款的價格模式下都必須有訂閱項目。

如要發布優惠，必須至少包含一個分期付款方案。

分期付款

優惠的期數。

JSON 表示法 
{
  "startTime": {
    object (DateTime)
  },
  "priceModel": {
    object (PriceModel)
  }
}
欄位
startTime

object (DateTime)

選用。分期付款的開始時間。每期付款的開始時間不得重複，但有一種情況例外：如果方案的 term.start_policy 為 IMMEDIATE，則第一期付款的 startTime 必須未設定。實際開始時間不會記錄在方案中，而是取決於訂單生效的時間。

如果方案的期數 term.start_policy 為 SCHEDULED_START_TIME，則第一期付款的 startTime 必須與 term.scheduled_start_time 相符。

如果優惠條款的 term.end_policy 為 SCHEDULED_END_TIME，則分期付款 startTime 必須早於 term.scheduled_end_time。如果是 AFTER_DURATION，則分期付款 startTime 必須早於優惠開始時間加上 term.duration_months 所計算出的時間。

分期付款的「startTime」不得早於優惠的「acceptDeadlineTime」。

分期付款開始時間必須嚴格依時間遞增順序排列。
priceModel

object (PriceModel)

選用。分期付款的價格模式。所有分期付款方案都必須採用相同的價格模式。

DateTime

代表民用時間 (或偶爾代表實際時間)。

這個型別可以透過幾種可能的方式表示民用時間：

  • 設定 utcOffset 但未設定 timeZone：日曆上某一天與世界標準時間有特定時差的民用時間。
  • 如果已設定 timeZone 但未設定 utcOffset：特定時區中某個日曆日期的民用時間。
  • 如果未設定 timeZone 和 utcOffset：日曆上以當地時間顯示的民用時間。

日期以西曆為主，

如果年、月或日為 0，則 DateTime 會分別視為沒有特定年、月或日。

如果設定了所有日期和時間欄位，且設定了 time_offset oneof 的任一情況，這個型別也可用於表示實際時間。建議改用 Timestamp 訊息表示實際時間。如果您的用途也需要儲存使用者的時區，可以在另一個欄位中完成。

這類型的彈性比某些應用程式的需求更高。請務必記錄並驗證應用程式的限制。

JSON 表示法 
{
  "year": integer,
  "month": integer,
  "day": integer,
  "hours": integer,
  "minutes": integer,
  "seconds": integer,
  "nanos": integer,

  // Union field time_offset can be only one of the following:
  "utcOffset": string,
  "timeZone": {
    object (TimeZone)
  }
  // End of list of possible types for union field time_offset.
}
欄位
year

integer

選用。日期年份。必須為 1 到 9999；如要指定不含年份的日期時間，請輸入 0。
month

integer

選用。月份。必須為 1 到 12；如要指定不含月份的日期時間，請輸入 0。
day

integer

選用。當月第幾日。必須為 1 到 31，並屬於有效的年和月；如要指定不含日期的日期時間，請輸入 0。
hours

integer

選用。一天中的小時，採用 24 小時制。值應介於 0 到 23 之間，預設為 0 (午夜)。API 可選擇允許使用「24:00:00」這類的值來表示營業打烊時間等情況。
minutes

integer

選用。一天中，每小時內的分鐘。值必須介於 0 到 59 之間，預設為 0。
seconds

integer

選用。在當下時間中，該分鐘的秒數。正常情況下，值必須介於 0 到 59 之間，預設為 0。如果 API 允許閏秒，則可允許值為 60。
nanos

integer

選用。秒數的小數，以奈秒為單位。值必須介於 0 到 999,999,999 之間，預設為 0。
聯集欄位 time_offset。選用。指定 DateTime 的世界標準時間偏移量或時區。請謹慎選擇，因為時區資料日後可能會變更 (例如，某個國家/地區修改日光節約時間的開始/結束日期，而受影響範圍內的未來 DateTime 已儲存)。如果省略，DateTime 會視為當地時間。time_offset 只能是下列其中一個設定：
utcOffset

string (Duration format)

世界標準時間時差。必須是整數秒，介於 -18 小時和 +18 小時之間。舉例來說，UTC 偏移量 -4:00 會表示為 { seconds: -14400 }。

時間長度以秒為單位，最多可有 9 個小數位數，並應以「s」結尾，例如："3.5s"。
timeZone

object (TimeZone)

時區。

TimeZone

代表 IANA 時區資料庫中的時區。

JSON 表示法 
{
  "id": string,
  "version": string
}
欄位
id

string

IANA 時區資料庫時區。例如「America/New_York」。
version

string

選用。IANA 時區資料庫版本號碼。例如「2019a」。

功能

用於說明服務層級自訂項目的其他詳細資料。

功能可用於區分同一產品的服務等級。如果產品只有一個服務等級，所有詳細資料都可納入產品說明文件。如果產品有多個服務層級，可以為每個服務層級指派不同的功能組合，藉此區分服務層級之間的主要差異。

除了自訂價格和其他交易詳細資料，私下提案還可自訂合作夥伴管理的產品行為。在這種情況下，自訂行為的詳細資料會使用特徵說明。

JSON 表示法 
{
  "displayName": string,
  "value": string
}
欄位
displayName

string

選用。使用者可理解的顯示文字，用於說明功能。應提供足夠的詳細資訊來識別功能，以便在不同的方案和服務層級之間建立功能關聯。必須填寫這項資訊才能發布優惠。長度上限為 128 個字元。允許使用下列 Unicode 屬性類別的字元：字母、數字、標點符號、符號和分隔符
value

string

選用。使用者可讀的顯示文字，反映特徵的值。用於 displayName 無法單獨擷取的變數特徵。長度上限為 3,000 個字元。允許使用下列 Unicode 屬性類別的字元：字母、數字、標點符號、符號和分隔符

ContractValue

優惠的合約價值。

JSON 表示法 
{
  "totalContractValue": {
    object (Money)
  }
}
欄位
totalContractValue

object (Money)

僅供輸出。這項優惠的合約總價值。只要要求「PRIVATE_OFFER_VIEW_FULL」，系統就會為所有非草稿的私密優惠設定這項值。如果是「草稿」狀態的私人方案，只有在設定好終端使用者的帳單帳戶，且價格和條款設定已完成到足以進行計算時，系統才會填入這項資訊。

RevenueShare

私密優惠的收益分潤資訊。如要進一步瞭解收益分享，包括如何決定價值，請參閱 https://docs.cloud.google.com/marketplace/docs/partners/revenue-share-scenarios。

不適用於 PRIVATE_OFFER_VIEW_BASIC，或草稿狀態的私密優惠。

如果是非草稿的私人提案，系統會根據下列項目填入這些欄位：

  • 2025 年 4 月 20 日後發布的方案一律會填入收益分潤欄位。
  • 如果 2025 年 4 月 20 日當天，發布的方案與有效且未過期的訂單相關聯，收益分享欄位才會填入資料。
JSON 表示法 
{
  "currentTermVendorNetRevenuePercent": {
    object (Decimal)
  },
  "renewalTermVendorNetRevenuePercent": {
    object (Decimal)
  }
}
欄位
currentTermVendorNetRevenuePercent

object (Decimal)

僅供輸出。目前生效的收益分成。

值的範圍介於 0 到 100 之間。舉例來說，80 代表供應商目前的收益分潤為 80%。供應商會保留 80% 的收益，。
renewalTermVendorNetRevenuePercent

object (Decimal)

僅供輸出。續約期間的預期收益分潤。如果優惠沒有續訂條款，則不包含這項資訊。

值的範圍介於 0 到 100 之間。舉例來說，80 代表供應商目前的收益分潤為 80%。續約後，供應商可保留 80% 的收益。。

狀態

優惠的狀態。

列舉
STATE_UNSPECIFIED 預設值。這個值不會使用。
DRAFT 優惠建立後的預設狀態，此時可編輯優惠。在其他州別，優惠內容無法編輯。
PUBLISHING 優惠正在發布中，滿足所有發布條件後，發布作業就會完成。
PUBLISHED 優惠已發布，客戶可以接受。
ACCEPTED 顧客已接受這項優惠。
CANCELLED 優惠在交易前遭到提供者取消。取消的優惠無法再由顧客接受。
EXPIRED 客戶未接受優惠，且優惠已過期。過期優惠無法再由顧客接受。
ENDED

優惠已結束。

已結束的優惠曾獲接受並生效，但現在已到期或終止。

PublishRequirementGoogleReview

Google 審查程序的相關資訊。

JSON 表示法 
{
  "reviewApproveTime": string
}
欄位
reviewApproveTime

string (Timestamp format)

僅供輸出。Google 審查程序的核准時間。

使用 RFC 3339，產生的輸出內容一律會經過 Z 正規化，並使用 0、3、6 或 9 個小數位數，也接受「Z」以外的偏移量。範例："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

ResellerContact

經銷商的聯絡資訊。

JSON 表示法 
{
  "contact": string,
  "email": string
}
欄位
contact

string

僅供輸出。此方案的經銷商聯絡人姓名。
email

string

僅供輸出。此優惠的經銷商聯絡人電子郵件地址。

OfferDealType

透過優惠交易的交易類型。優惠的交易類型是決定收益分潤的因素之一。

列舉
OFFER_DEAL_TYPE_UNSPECIFIED 預設值。這個值不會使用。
CHANNEL_SHIFT 這項方案對應於 Google Cloud 上工作負載的現有商業協議，該協議將轉移至 Cloud Marketplace。
MIGRATION 這項優惠適用於先前不在 Google Cloud 的工作負載，現在要轉移至 Google Cloud 的情況，且該工作負載已有商業協議。
NATIVE_RENEWAL 這項優惠是針對最初在 Google Cloud Marketplace 交易的續約。
NEW

這項優惠適用於透過 Google Cloud Marketplace 進行的新交易。

如果優惠修改的另一項私密優惠尚未到期，且修改後的私密優惠交易類型為 MIGRATION、CHANNEL_SHIFT 或 NATIVE_RENEWAL，則不允許使用這個值。

PartnerContact

合作夥伴代表的聯絡資訊。

JSON 表示法 
{
  "contact": string,
  "email": string
}
欄位
contact

string

選用。顯示識別合作夥伴銷售聯絡人的文字。向消費者顯示。發布優惠時必須提供這項資訊。長度上限為 256 個半形字元。
email

string

選用。合作夥伴銷售聯絡人的電子郵件地址。向消費者顯示。發布優惠時，系統會驗證提供的電子郵件地址格式，但不會驗證電子郵件地址是否確實存在、可接收電子郵件或正常運作。

客戶

顧客資訊。

JSON 表示法 
{
  "entityTitle": string,
  "contact": string,
  "email": string,
  "address": string,
  "targetBillingAccount": string
}
欄位
entityTitle

string

選用。識別客戶實體的字串 (例如客戶的機構或公司名稱)。發布優惠時必須提供這項資訊。長度上限為 256 個半形字元。
contact

string

選用。用於識別客戶聯絡人的字串。發布優惠時必須提供這項資訊。長度上限為 256 個半形字元。
email

string

選用。客戶聯絡人的電子郵件地址。如有提供，必須是格式正確的電子郵件地址。
address
(deprecated)

string

僅供輸出。客戶機構的法定地址。這個欄位無法再設定，但會保留，以便從已設定地址的現有方案傳回資料。
targetBillingAccount

string

選用。這項優惠適用的客戶帳單帳戶。發布私密優惠後，目標帳單帳戶的帳單管理員即可接受。如果客戶接受優惠，並將產生的訂單移至新的帳單帳戶，這個欄位仍會顯示提供私密優惠的原始帳單帳戶。發布優惠時必須提供這項資訊。

如要發布這項私密優惠，請按照下列步驟操作：

  • 帳單帳戶必須存在。
  • 帳單帳戶不得處於免費試用期。
  • 帳單帳戶必須遵守 Marketplace 轉售政策。
  • 禁止使用經銷商上層帳單帳戶。除非服務已啟用轉售功能，否則不得使用經銷商子帳戶。

格式：billingAccounts/012345-567890-ABCDEF

字詞

設定方案期限和續訂選項。向客戶提供特定期限的私密優惠，即代表向客戶保證，產品在該期限內將持續提供給他們。

JSON 表示法 
{
  "startPolicy": enum (StartPolicy),
  "scheduledStartTime": {
    object (DateTime)
  },
  "endPolicy": enum (EndPolicy),
  "effectiveTermEndTime": {
    object (DateTime)
  },

  // Union field end_policy_data can be only one of the following:
  "durationMonths": integer,
  "scheduledEndTime": {
    object (DateTime)
  }
  // End of list of possible types for union field end_policy_data.

  // Union field renewal can be only one of the following:
  "maxRenewalCount": integer,
  "unlimitedRenewal": boolean
  // End of list of possible types for union field renewal.
}
欄位
startPolicy

enum (StartPolicy)

選用。定義結果訂單的開始時間。發布優惠時必須設定。
scheduledStartTime

object (DateTime)

選用。優惠的預定開始時間。不得超過發布時間後的一年。

如果開始政策為 SCHEDULED_START_TIME，發布方案時必須提供 America/Los_Angeles 時區的未來時間 (以天為界)。

如果優惠是修改其他私密或標準優惠，則預定開始時間必須：

  • 如果優惠的結束政策不是 MATCH_AMENDED_OFFER，則必須早於或等於修訂優惠的結束時間。否則必須嚴格早於修訂後優惠的結束時間。
  • 如果修改的私密優惠包含自訂分期付款，則必須在下一個待處理分期付款的開始時間之前或當天完成。舉例來說，如果修訂後的方案在 1 月 1 日、2 月 1 日、3 月 1 日和 4 月 1 日有分期付款，而今天是 2 月 15 日，則新方案的 scheduledStartTime 必須在 3 月 1 日或之前。
endPolicy

enum (EndPolicy)

選用。定義優惠結束時間。發布優惠時必須設定。
effectiveTermEndTime

object (DateTime)

僅供輸出。目前優惠方案的預計結束時間。

每個優惠期結束時，與有效訂單相關聯的優惠會續約或終止。續訂方案後，新的效期會開始，這個值也會變更，反映新效期的結束時間。優惠結束後，系統就不會再設定這個值，而是設定 endTime。

如果基本標準方案採用訂閱價格模式，當優惠方案到期且未續訂時，相關聯的訂單也會終止。否則相關聯的訂單不會結束，仍處於有效狀態。

PRIVATE_OFFER_VIEW_BASIC 不包含這項資訊。如果優惠尚未結束，且優惠已開始或可從其他欄位衍生值，則 PRIVATE_OFFER_VIEW_FULL 會包含這項資訊。

如果優惠尚未開始，只要符合下列任一條件，系統就會設定這個欄位。

  • 優惠組合 term.scheduled_end_time。
  • 優惠設定 term.scheduled_start_time 和 term.duration_months，優惠的 term.end_policy 不是 MATCH_AMENDED_OFFER，且優惠未將 standardInterval 設為 MONTHLY_POSTPAY。
聯集欄位 end_policy_data。結束政策的額外資料。end_policy_data 只能是下列其中一個設定：
durationMonths

integer

選用。優惠期長度 (以月為單位)。優惠將在上述時間過後，於當月同一天結束。如果該日期不存在，優惠將於當月最後一天結束。舉例來說，如果優惠於 2024 年 1 月 31 日開始，為期 13 個月，則優惠將於 2025 年 2 月 28 日結束。如果結束政策為 AFTER_DURATION 或 MATCH_AMENDED_OFFER，就必須設定為發布優惠，且必須是正值。

包括所有續約條款在內，優惠期限最長不得超過 7 年。舉例來說，如果 durationMonths 為 9，且 term.max_renewal_count 為 9，則優惠期限最長可達 90 個月，超過 7 年的上限。
scheduledEndTime

object (DateTime)

選用。優惠的指定結束時間。如果結束政策為 SCHEDULED_END_TIME，則必須設為發布優惠。設定時間時，必須是未來的時間，且位於 America/Los_Angeles 時區的日期界線，並須晚於 term.scheduled_start_time (如適用)。
聯集欄位 renewal。定義方案的續訂政策。renewal 只能是下列其中一個設定：
maxRenewalCount

integer

選用。初始期限結束後，可續約的次數上限。這個欄位僅適用於間隔為「MONTHLY_PRORATED」、「MONTHLY_NOT_PRORATED」、「QUARTERLY_NOT_PRORATED」或「YEARLY_NOT_PRORATED」的標準間隔方案。其他類型的優惠無法續訂。

舉例來說，如果初始約期為 1 年，最多可續約 3 次，則客戶在初始約期結束後，最多可再續約 3 年。客戶可自行決定是否續訂優惠。

允許顧客續訂優惠，並不保證顧客在續訂日期仍可續訂優惠產品。

如果優惠的續約次數上限為 0，就無法續約。不能是負值。
unlimitedRenewal
(deprecated)

boolean

僅供輸出。已淘汰：只有在現有優惠的標準間隔為「MONTHLY_POSTPAY」時，這個欄位才能設為 true。自 2024 年 5 月起，我們不再允許無限次續訂。

StartPolicy

定義優惠的開始時間。

列舉
START_POLICY_UNSPECIFIED 預設值。這個值不會使用。
IMMEDIATE 如果不需要合作夥伴核准，客戶接受優惠後，系統會立即建立訂單；如果需要核准，合作夥伴核准購買後，系統會立即建立訂單。這個列舉值無法與 term.scheduled_start_time 合併。
SCHEDULED_START_TIME 系統會從排定的開始時間開始排序。

EndPolicy

定義優惠結束時間。

列舉
END_POLICY_UNSPECIFIED 預設值。這個值不會使用。
AFTER_DURATION 優惠會在指定時間後結束。如果設定這項屬性，durationMonths 必須為正數。
SCHEDULED_END_TIME 優惠會在排定的時間結束。
MATCH_AMENDED_OFFER

與修訂後的優惠共同終止 - 優惠會在修訂後的優惠期結束時終止

舉例來說，如果修訂後的優惠於 2024 年 1 月 15 日生效，且優惠期間為 6 個月，則優惠將於 2024 年 7 月 15 日結束。如果目前的優惠與先前的優惠同時結束，且目前的優惠於 2024 年 5 月 6 日開始，則仍會在 2024 年 7 月 15 日結束。假設目前的優惠續約 3 次，則現有優惠的條款如下：

  1. 2024 年 5 月 6 日 - 2024 年 7 月 15 日 (第一期，於 2024 年 7 月 15 日結束，與修訂的優惠方案同步)
  2. 2024 年 7 月 15 日 - 2025 年 1 月 15 日 (第一個續訂期)
  3. 2025 年 1 月 15 日 - 2025 年 7 月 15 日 (第二個續約期)
  4. 2025 年 7 月 15 日 - 2026 年 1 月 15 日 (第三次續約期)

反之，如果現有方案與修訂方案的到期日不同 (例如 endPolicy 為 AFTER_DURATION)，則條款如下：

  1. 2024 年 5 月 6 日 - 2024 年 11 月 6 日 (第一期，於 11 月 6 日結束，不適用共同終止)
  2. 2024 年 11 月 6 日 - 2025 年 5 月 6 日 (首次續約期)
  3. 2025 年 5 月 6 日 - 2025 年 11 月 6 日 (第二次續約期)
  4. 2025 年 11 月 6 日 - 2026 年 5 月 6 日 (第三個續約期)

如果設定這項政策，就必須符合下列條件：

  • singleProductOffer.amended_private_offer 必須設定，且不得結束經修訂的私密優惠。
  • 不得變更按比例計算政策 (例如，不得在 MONTHLY_PRORATED 和 MONTHLY_NOT_PRORATED 之間切換)。
  • 目前的優惠不得有自訂間隔 (即設定 customIntervalPrice)。
  • term.duration_months必須與修訂後的私密優惠期間一致。
  • 修訂後的私密優惠不得有 MONTHLY_POSTPAY 的標準間隔。

但我們目前尚未支援這項功能。

方法

cancel

 取消目標 PrivateOffer。

create

 在指定專案和位置建立新的 PrivateOffer。

delete

 刪除目標 PrivateOffer。

get

 取得單一 PrivateOffer 的詳細資料。

list

 列出指定上層的 PrivateOffer。

patch

 更新目標 PrivateOffer。

publish

 發布目標 PrivateOffer。

resolveAmendmentTarget

 建立新的 PrivateOffer 時，解決必須修改的現有方案。