Order

訂單實體。注意:1. 除非另有指定,所有層級的所有字串都必須少於 1000 個半形字元。2. 除非另有指定,否則所有層級的所有重複欄位計數都必須少於 50。3. 如有指定,所有層級的所有時間戳記都必須是有效的時間戳記。

JSON 表示法
{
  "googleOrderId": string,
  "merchantOrderId": string,
  "userVisibleOrderId": string,
  "userVisibleStateLabel": string,
  "buyerInfo": {
    object (UserInfo)
  },
  "image": {
    object (Image)
  },
  "createTime": string,
  "lastUpdateTime": string,
  "transactionMerchant": {
    object (Merchant)
  },
  "contents": {
    object (Contents)
  },
  "priceAttributes": [
    {
      object (PriceAttribute)
    }
  ],
  "followUpActions": [
    {
      object (Action)
    }
  ],
  "paymentData": {
    object (PaymentData)
  },
  "termsOfServiceUrl": string,
  "note": string,
  "promotions": [
    {
      object (Promotion)
    }
  ],
  "disclosures": [
    {
      object (Disclosure)
    }
  ],
  "vertical": {
    "@type": string,
    field1: ...,
    ...
  },

  // Union field verticals can be only one of the following:
  "purchase": {
    object (PurchaseOrderExtension)
  },
  "ticket": {
    object (TicketOrderExtension)
  }
  // End of list of possible types for union field verticals.
}
欄位
googleOrderId

string

Google 指派的訂單 ID。

merchantOrderId

string

必填:商家指派的內部訂單 ID。此 ID 不得重複,而且是後續的訂單更新作業時必填。這個 ID 可以設為提供的 googleOrderId 或任何其他不重複的值。請注意,向使用者顯示的 ID 是 userVisibleOrderId,可能是另一個更易於使用的值。長度上限為 128 個半形字元。

userVisibleOrderId

string

參照目前訂單的使用者專屬 ID。在網站、應用程式和電子郵件等其他情況下,這個 ID 應與此訂單顯示的 ID 保持一致。

userVisibleStateLabel
(deprecated)

string

已淘汰:請改用 OrderExtensions 狀態。此訂單狀態的使用者可見標籤。

buyerInfo

object (UserInfo)

買家相關資訊。

image

object (Image)

與訂單相關聯的圖片。

createTime

string (Timestamp format)

必填:訂單建立的日期和時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,範例:"2014-10-02T15:01:23.045123456Z"

lastUpdateTime

string (Timestamp format)

上次更新訂單的日期和時間。此為 OrderUpdate 必填屬性。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,範例:"2014-10-02T15:01:23.045123456Z"

transactionMerchant

object (Merchant)

協助結帳的商家。這可能與委刊項層級供應商設定不同。例如:Expedia Order,內含 ANA 的委刊項。

contents

object (Contents)

必要:排序一組委刊項的內容。

priceAttributes[]

object (PriceAttribute)

價格、折扣、稅金等。

followUpActions[]

object (Action)

依訂單層級的後續追蹤動作。

paymentData

object (PaymentData)

訂單的付款相關資料。

termsOfServiceUrl

string

訂單/提案適用的服務條款連結。

note

string

訂單附加的附註。

promotions[]

object (Promotion)

與這筆訂單相關聯的所有促銷活動。

disclosures[]

object (Disclosure)

與這筆訂單相關的揭露事項。

vertical
(deprecated)

object

已淘汰:請改用產業。除非在某些委刊項中覆寫設定,否則這些屬性會套用至所有委刊項。這個產業必須與委刊項層級產業類型相符。可能的值:google.actions.orders.v3.verticals.purchase.PurchaseOrderExtension google.actions.orders.v3.verticals.ticket.TicketOrderExtension

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如:{ "id": 1234, "@type": "types.example.com/standard/id" }.

聯集欄位 verticals。除非在某些委刊項中覆寫設定,否則這些屬性會套用至所有委刊項。這個產業必須與委刊項層級產業類型相符。verticals 只能是下列其中一項:
purchase

object (PurchaseOrderExtension)

訂購單

ticket

object (TicketOrderExtension)

票券訂單

UserInfo

使用者的相關資訊。用來代表與訂單相關聯的使用者資訊。

JSON 表示法
{
  "email": string,
  "firstName": string,
  "lastName": string,
  "displayName": string,
  "phoneNumbers": [
    {
      object (PhoneNumber)
    }
  ]
}
欄位
email

string

使用者電子郵件地址,例如:janedoe@gmail.com

firstName

string

使用者的名字。

lastName

string

使用者的姓氏。

displayName

string

使用者的顯示名稱可能與姓氏或名字不同。

phoneNumbers[]

object (PhoneNumber)

使用者的電話號碼。

PhoneNumber

標準電話號碼表示法。

JSON 表示法
{
  "e164PhoneNumber": string,
  "extension": string,
  "preferredDomesticCarrierCode": string
}
欄位
e164PhoneNumber

string

如為國際電信聯盟 (ITU) Recommendation E.164 所定義的 E.164 電話號碼。維基連結:https://en.wikipedia.org/wiki/E.164

extension

string

ITU 建議的延伸類型並非標準化,除了可定義為長度最多 40 位數的一組數字之外。定義為字串,為了能在延伸模組中使用開頭的零 (因為沒有定義標準,組織可完全自由執行這類動作)。除了數字以外,「,」(代表等候) 等其他撥號字元可能會儲存在這裡。舉例來說,在 xxx-xxx-xxxx ext. 123 中,「123」是副檔名。

preferredDomesticCarrierCode

string

撥打這個電話號碼時建議使用的電信業者選擇代碼。此外,在某些國家/地區,從市話或手機撥打時,也必須撥打該號碼 (反之亦然)。舉例來說,在哥倫比亞地區,從手機撥打國內市內電話時,必須先撥打「3」,才能輸入電話號碼,反之亦然。https://en.wikipedia.org/wiki/Telephone_numbers_in_Colombia (https://en.wikipedia.org/wiki/Brazilian_Carrier_Selection_Code)

請注意,這是「偏好」代碼,表示其他代碼也可以正常運作。

映像檔

資訊卡中顯示的圖片。

JSON 表示法
{
  "url": string,
  "accessibilityText": string,
  "height": number,
  "width": number
}
欄位
url

string

圖片的來源網址。圖片可以是 JPG、PNG 和 GIF (動畫和非動畫)。例如:https://www.agentx.com/logo.png。這是必要項目。

accessibilityText

string

圖片的文字說明,供無障礙功能使用,例如螢幕閱讀器。這是必要項目。

height

number

圖片的高度 (以像素為單位)。(選用)

width

number

圖片的寬度 (以像素為單位)。(選用)

商家

購物車/訂單/明細項目的商家。

JSON 表示法
{
  "id": string,
  "name": string,
  "image": {
    object (Image)
  },
  "phoneNumbers": [
    {
      object (PhoneNumber)
    }
  ],
  "address": {
    object (Location)
  }
}
欄位
id

string

指派給商家的選用 ID (如有)。

name

string

商家名稱,例如「烤麵包機」。

image

object (Image)

與商家相關聯的圖片。

phoneNumbers[]

object (PhoneNumber)

商家的電話號碼。

address

object (Location)

商家地址。

位置

代表位置的容器。

JSON 表示法
{
  "coordinates": {
    object (LatLng)
  },
  "formattedAddress": string,
  "zipCode": string,
  "city": string,
  "postalAddress": {
    object (PostalAddress)
  },
  "name": string,
  "phoneNumber": string,
  "notes": string,
  "placeId": string
}
欄位
coordinates

object (LatLng)

地理座標。必須具備 [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] 權限。

formattedAddress

string

顯示地址,例如「110 臺北市信義區信義路 5 段 7 號」必須具備 [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] 權限。

zipCode

string

郵遞區號。需要有 [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] 或 [DEVICE_COARSE_LOCATION] [google.actions.v2.Permission.DEVICE_COARSE_LOCATION] 權限。

city

string

市區鄉鎮。需要有 [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] 或 [DEVICE_COARSE_LOCATION] [google.actions.v2.Permission.DEVICE_COARSE_LOCATION] 權限。

postalAddress

object (PostalAddress)

郵政地址:需要有 [DEVICE_PRECISE_LOCATION] [google.actions.v2.Permission.DEVICE_PRECISE_LOCATION] 或 [DEVICE_COARSE_LOCATION] [google.actions.v2.Permission.DEVICE_COARSE_LOCATION] 權限。

name

string

地點的名稱。

phoneNumber

string

地點的電話號碼,例如商家所在地點的聯絡電話或送貨地點的電話號碼。

notes

string

地點附註。

placeId

string

placeId 可與 Places API 搭配使用,以擷取地點的詳細資料。詳情請參閱 https://developers.google.com/places/web-service/place-id

LatLng

表示經緯度組合的物件。這個物件會同時指出經度和緯度的度數;除非另有說明,否則必須符合 WGS84 標準。此外,值必須在正規化範圍內。

JSON 表示法
{
  "latitude": number,
  "longitude": number
}
欄位
latitude

number

緯度度數,必須介於 [-90.0, +90.0] 的範圍中。

longitude

number

經度度數,必須介於 [-180.0, +180.0] 的範圍中。

PostalAddress

表示郵寄地址,如郵政快遞或付款地址。如果是郵寄地址,郵政服務可將貨品寄送到場所、郵政信箱或類似位置。此表示法並不適用於建立地理位置 (街道、鄉鎮或山區) 的模型。

在一般使用情況下,系統會根據處理作業的類型,以使用者輸入或匯入現有資料的方式來建立地址。

地址輸入/編輯的建議:- 使用支援 i18n 的地址小工具 (例如 https://github.com/google/libaddressinput):在使用該欄位的國家/地區之外,不應向使用者顯示 UI 元素來輸入或編輯欄位。

如要進一步瞭解如何使用這個結構定義,請參閱:https://support.google.com/business/answer/6397478

JSON 表示法
{
  "revision": number,
  "regionCode": string,
  "languageCode": string,
  "postalCode": string,
  "sortingCode": string,
  "administrativeArea": string,
  "locality": string,
  "sublocality": string,
  "addressLines": [
    string
  ],
  "recipients": [
    string
  ],
  "organization": string
}
欄位
revision

number

PostalAddress 的結構定義修訂版本。這個欄位的值必須設為 0,即代表最新的修訂版本。

所有新的修訂版本都必須能夠與舊的修訂版本回溯相容。

regionCode

string

必要欄位。地址所在國家/地區的 CLDR 地區代碼。這個代碼絕非透過推測而得出,並且是由使用者自行確保該值正確無誤。詳情請參閱 http://cldr.unicode.org/http://www.unicode.org/cldr/charts/30/supplemental/territory_information.html。例如:瑞士適用的「CH」。

languageCode

string

選用設定。這個地址內容的 BCP-47 語言代碼 (如果已知)。通常是輸入表單的 UI 語言,或是符合地址的國家/地區所用的其中一個語言,或是使用音譯的對應項目。這個欄位可能會影響某些國家/地區的格式設定,但是不會影響資料的正確性,也絕不會影響任何驗證或其他非格式的相關作業。

如果不知道這個值為何,則應省略該值 (而非指定可能不正確的預設值)。

例如:「zh-Hant」、「ja」、「ja-Latn」、「en」。

postalCode

string

選用設定。地址的郵遞區號。並非所有國家/地區都使用郵遞區號或要求提供郵遞區號,但在使用郵遞區號時,可能會觸發地址的其他部分 (例如美國的州/郵遞區號驗證) 進行驗證。

sortingCode

string

選用設定。國家/地區專屬的其他分類代碼。大多數國家/地區並不使用這個代碼。使用此值時,這個值可以是一串字串 (例如「CEDEX」),後面接著一個數字 (例如「CEDEX 7」),也可以只是一個數字,代表「部門代碼」(牙買加)、「寄送區域指標」(馬拉威) 或「郵局指示器」(例如像牙海岸)。

administrativeArea

string

選用設定。最高行政區,用於國家/地區的郵遞地址。例如,此值可以是州、省或縣。以西班牙為例來具體說明,此欄位的值為省,而非自治區 (例如「巴塞隆納」省,而不是「加泰隆尼亞」自治區)。許多國家/地區的郵寄地址並沒有使用行政區。例如,在瑞士,這應該不要填入。

locality

string

選用設定。一般是指地址的縣市/鄉鎮部分。例如:美國城市、義大利市鎮、英國郵鎮。如果是未明確定義縣市或其縣市不適用此結構的地區,請將 locality 留白,改用 addressLines。

sublocality

string

選用設定。地址的縣市以下行政區,例如社區、自治市鎮、區等。

addressLines[]

string

非結構化的地址行,說明地址的低層級項目。

由於 addressLines 中的值不會有類型資訊,而且有時在單一欄位中可能會包含多個值 (例如「Austin, TX」),因此地址行的順序務必要明確。地址行的順序應為該地址所在國家/地區的「信封書寫順序」。在信封書寫順序可能不盡相同的地區 (如日本),可使用 address_language 讓地址更明確 (例如「ja」表示由大到小的排序,而「ja-Latn」或「en」則表示由小到大)。如此一來,您便可以根據語言來選取明確度最高的地址行。

地址允許的最小結構表示法是包含一個 regionCode,並將其餘所有資訊放置在 addressLines 中。您可以在幾乎不使用地理定位的情况下,設定這類地址的格式,但至少在地址局部解析完畢之前,您無法對地址的任何組成部分進行語意推論。

如要處理完全非結構化的地址,我們建議您只建立包含 regionCode 和 addressLines 的地址,並使用地理定位來進行 (而非猜測地址的哪些部分應該是縣市還是行政區)。

recipients[]

string

選用設定。地址的收件人。在某些情況下,這個欄位可能會包含多行資訊。例如,其中可能包含「代收者」資訊。

organization

string

選用設定。地址中的機構名稱。

目錄

委刊項的包裝函式。

JSON 表示法
{
  "lineItems": [
    {
      object (LineItem)
    }
  ]
}
欄位
lineItems[]

object (LineItem)

訂單委刊項清單。至少要有 1 個委刊項,但最多只能有 50 個。所有委刊項都必須屬於相同的產業。

LineItem

一個委刊項包含一個產業。訂單或購物車中可以有多個相同產業的委刊項。請根據其用途,在垂直 proto 中定義子委刊項/外掛程式等項目。注意:1. 除非另有指定,所有層級的所有字串都必須少於 1000 個半形字元。2. 除非另有指定,否則所有層級的所有重複欄位計數都必須少於 50。3. 如有指定,所有層級的所有時間戳記都必須是有效的時間戳記。

JSON 表示法
{
  "id": string,
  "name": string,
  "userVisibleStateLabel": string,
  "provider": {
    object (Merchant)
  },
  "priceAttributes": [
    {
      object (PriceAttribute)
    }
  ],
  "followUpActions": [
    {
      object (Action)
    }
  ],
  "recipients": [
    {
      object (UserInfo)
    }
  ],
  "image": {
    object (Image)
  },
  "description": string,
  "notes": [
    string
  ],
  "disclosures": [
    {
      object (Disclosure)
    }
  ],
  "vertical": {
    "@type": string,
    field1: ...,
    ...
  },

  // Union field verticals can be only one of the following:
  "purchase": {
    object (PurchaseItemExtension)
  },
  "reservation": {
    object (ReservationItemExtension)
  }
  // End of list of possible types for union field verticals.
}
欄位
id

string

必要:委刊項指派給商家 ID。用於識別現有委刊項,以套用部分更新。長度上限為 64 個半形字元。

name

string

收據上的明細項目名稱。長度上限為 100 個半形字元。

userVisibleStateLabel
(deprecated)

string

已淘汰,請改用垂直層級狀態。舉例來說,如果是購物,請使用 PurchaseOrderExtension.status。這個委刊項狀態的使用者可見標籤。

provider

object (Merchant)

特定委刊項的供應商 (若與整體訂單不同)。例如:具有委刊項供應商 ANA 的 Expedia 訂單。

priceAttributes[]

object (PriceAttribute)

委刊項層級價格和調整項。

followUpActions[]

object (Action)

對委刊項的後續行動。

recipients[]

object (UserInfo)

委刊項層級客戶,可能與訂單層級的買方不同。示例:使用者 X 以使用者 Y 的名稱預訂了餐廳訂位。

image

object (Image)

與此項目相關聯的小型圖片 (如果有的話)。

description

string

委刊項說明。

notes[]

string

適用於這個特定委刊項的其他附註,例如取消政策。

disclosures[]

object (Disclosure)

與這個委刊項相關的揭露聲明。

vertical
(deprecated)

object

已淘汰:請改用產業。必要:根據類型/產業的委刊項語意內容。每個類別都應提供專屬的執行要求詳細資料。必須是下列其中一個值:google.actions.orders.v3.verticals.purchase.PurchaseItemExtension google.actions.orders.v3.verticals.reservation.ReservationItemExtension google.actions.orders.v3.verticals.ticket.TicketItemExtension

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如:{ "id": 1234, "@type": "types.example.com/standard/id" }.

聯集欄位 verticals。必要:根據類型/產業的委刊項語意內容。每個類別都應提供專屬的執行要求詳細資料。verticals 只能是下列其中一項:
purchase

object (PurchaseItemExtension)

購買商品,例如商品、食物等。

reservation

object (ReservationItemExtension)

預訂餐廳、剪髮等訂單。

PriceAttribute

訂單或委刊項的價格屬性。

JSON 表示法
{
  "type": enum (Type),
  "name": string,
  "state": enum (State),
  "taxIncluded": boolean,

  // Union field spec can be only one of the following:
  "amount": {
    object (Money)
  },
  "amountMillipercentage": number
  // End of list of possible types for union field spec.
}
欄位
type

enum (Type)

必填:金額屬性。

name

string

必要:使用者看到的價格屬性字串。此內容是由商家傳送和本地化。

state

enum (State)

必填:價格狀態:預估值與實際價格。

taxIncluded

boolean

價格是否含稅。

聯集欄位 spec。代表金額或千百分比。spec 只能是下列其中一項:
amount

object (Money)

金額。

amountMillipercentage
(deprecated)

number

百分比規格到百分比的 1/1000。例如:8.750% 會顯示為 8750,負百分比則代表折扣百分比。即將淘汰這個欄位。如果需要具體用途,可以考慮重新加入。

類型

代表金額類型。

列舉
TYPE_UNSPECIFIED 未指定類型,用戶端不應明確設定此類型。
REGULAR 套用任何折扣前的一般顯示價格。
DISCOUNT 系統會從小計中扣除值。
TAX 要計入小計。
DELIVERY 要計入小計。
SUBTOTAL 小計:可能會加收某些費用。
FEE 任何額外費用。
GRATUITY 要計入小計。
TOTAL 顯示的訂單或委刊項價格。

狀態

代表價格狀態。

列舉
STATE_UNSPECIFIED 未指定。
ESTIMATE 價格只是預估值。
ACTUAL 實際向使用者收取的實際價格。

金額

代表金額與其貨幣類型。

JSON 表示法
{
  "currencyCode": string,
  "amountInMicros": string
}
欄位
currencyCode

string

ISO 4217 定義的貨幣代碼 (由 3 個字母組成)。

amountInMicros

string (int64 format)

金額,以微量為單位。舉例來說,這個欄位應設為 $1.99 的 1990000。

動作

與訂單或委刊項相關的後續動作。

JSON 表示法
{
  "type": enum (Type),
  "title": string,
  "openUrlAction": {
    object (OpenUrlAction)
  },
  "actionMetadata": {
    object (ActionMetadata)
  }
}
欄位
type

enum (Type)

必要:動作類型。

title

string

向使用者顯示的動作名稱或標籤。長度上限為 100 個半形字元。

openUrlAction

object (OpenUrlAction)

要採取的行動。

actionMetadata

object (ActionMetadata)

與動作相關聯的中繼資料。

類型

可能的後續行動。

列舉
TYPE_UNSPECIFIED 未指定的動作。
VIEW_DETAILS 「查看訂單詳細資料」動作。
MODIFY 修改訂單動作。
CANCEL 取消訂單動作。
RETURN 退貨訂單動作。
EXCHANGE 廣告交易平台訂單動作。
EMAIL

電子郵件動作。不再支援 EMAIL 和 CALL 類型。openUrlAction.url 可做為電話號碼或電子郵件使用。

CALL

行動號召。

REORDER 重新排序動作
REVIEW 查看訂單動作。
CUSTOMER_SERVICE 請與客服人員聯絡。
FIX_ISSUE 引導至商家的網站或應用程式修正問題。
DIRECTION 路線連結。

OpenUrlAction

開啟指定網址。

JSON 表示法
{
  "url": string,
  "androidApp": {
    object (AndroidApp)
  },
  "urlTypeHint": enum (UrlTypeHint)
}
欄位
url

string

網址欄位,可以是下列任一值:- 用來開啟應用程式連結應用程式或網頁的 http/https 網址

androidApp

object (AndroidApp)

Android 應用程式的相關資訊 (如果網址會預期由 Android 應用程式執行)。

urlTypeHint

enum (UrlTypeHint)

表示網址類型的提示。

AndroidApp

針對執行要求限制的 Android 應用程式規格

JSON 表示法
{
  "packageName": string,
  "versions": [
    {
      object (VersionFilter)
    }
  ]
}
欄位
packageName

string

指定 Android 執行要求時,必須指定套件名稱套件名稱。

versions[]

object (VersionFilter)

如果您指定多個篩選條件,只要符合任何篩選條件,就會觸發應用程式。

VersionFilter

如果需要應用程式的特定版本,則應加入 VersionFilter。

JSON 表示法
{
  "minVersion": number,
  "maxVersion": number
}
欄位
minVersion

number

最小版本代碼或 0 (含首尾)。

maxVersion

number

最高版本代碼 (含首尾)。視為 [minVersion:maxVersion] 的範圍。空值範圍是指任何版本。範例:如要指定單一版本,請使用:[target_version:target_version]。如要指定任何版本,請保留 minVersion 和 maxVersion。如要指定直到 maxVersion 之前的所有版本,請勿指定 minVersion。如要指定 minVersion 的所有版本,請勿指定 maxVersion。

UrlTypeHint

不同類型的網址提示。

列舉
URL_TYPE_HINT_UNSPECIFIED 未指定
AMP_CONTENT 直接指向 AMP 內容的網址,或是透過 <link rel="amphtml"> 參照 AMP 內容的標準網址。

ActionMetadata

每個動作的相關中繼資料。

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

string (Timestamp format)

這個動作的到期時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,範例:"2014-10-02T15:01:23.045123456Z"

揭露事項

可能向使用者顯示的產品、服務或政策揭露事項。

JSON 表示法
{
  "title": string,
  "disclosureText": {
    object (DisclosureText)
  },
  "presentationOptions": {
    object (DisclosurePresentationOptions)
  }
}
欄位
title

string

揭露事項的標題。例如:「安全性資訊」。

disclosureText

object (DisclosureText)

揭露事項內容。可以使用網頁連結。

presentationOptions

object (DisclosurePresentationOptions)

揭露聲明的呈現選項。

DisclosureText

代表包含網頁連結的純文字。

JSON 表示法
{
  "template": string,
  "textLinks": [
    {
      object (TextLink)
    }
  ]
}
欄位
template

string

要顯示的文字,包含每個要插入的文字連結,例如「{0}」和「{1}」等預留位置。例如:「警告:本產品可能會接觸加州已知會導致癌症的化學物質。如需更多資訊,請前往 {0}。」這類揭露聲明文字不得包含任何宣傳或類似廣告的內容。

DisclosurePresentationOptions

揭露聲明的呈現選項。

JSON 表示法
{
  "presentationRequirement": enum (PresentationRequirement),
  "initiallyExpanded": boolean
}
欄位
presentationRequirement

enum (PresentationRequirement)

揭露事項的呈現規定。

initiallyExpanded

boolean

揭露事項的內容是否一開始應該展開。預設為收合狀態。

PresentationRequirement

揭露事項的呈現規定。

列舉
REQUIREMENT_UNSPECIFIED 未指定的要求。請勿明確設定。
REQUIREMENT_OPTIONAL 揭露事項為選用項目。如果裝置不支援顯示揭露事項,就可以略過此步驟。
REQUIREMENT_REQUIRED 必須揭露這項資訊。如果裝置不支援顯示揭露事項,使用者就能直接撥打電話給對話。

PurchaseItemExtension

「購買產業」中的委刊項內容。

JSON 表示法
{
  "status": enum (PurchaseStatus),
  "userVisibleStatusLabel": string,
  "type": enum (PurchaseType),
  "productId": string,
  "quantity": number,
  "unitMeasure": {
    object (MerchantUnitMeasure)
  },
  "returnsInfo": {
    object (PurchaseReturnsInfo)
  },
  "fulfillmentInfo": {
    object (PurchaseFulfillmentInfo)
  },
  "itemOptions": [
    {
      object (ItemOption)
    }
  ],
  "extension": {
    "@type": string,
    field1: ...,
    ...
  },
  "productDetails": {
    object (ProductDetails)
  }
}
欄位
status

enum (PurchaseStatus)

必要:委刊項層級狀態。

userVisibleStatusLabel

string

必要:使用者能夠看見狀態的標籤/字串。長度上限為 50 個半形字元。

type

enum (PurchaseType)

必填:購買類型。

productId
(deprecated)

string

與這個委刊項相關聯的產品或優惠 ID。

quantity

number

商品的數量。

unitMeasure

object (MerchantUnitMeasure)

單位測量。以所選單位指定項目大小。系統會根據尺寸和有效價格來決定單位價格。

returnsInfo

object (PurchaseReturnsInfo)

傳回這個明細項目的資訊。如果未設定,這個委刊項會沿用訂單層級傳回資訊。

fulfillmentInfo

object (PurchaseFulfillmentInfo)

這個委刊項的出貨資訊。如果未設定,這個委刊項會沿用訂單層級的出貨資訊。

itemOptions[]

object (ItemOption)

其他附加內容或子作品。

extension

object

商家與 Google 之間交換的任何額外欄位。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如:{ "id": 1234, "@type": "types.example.com/standard/id" }.

productDetails

object (ProductDetails)

產品的詳細資料。

PurchaseStatus

與訂購單或特定委刊項相關聯的購買狀態。

列舉
PURCHASE_STATUS_UNSPECIFIED 狀態不明。
READY_FOR_PICKUP 已可取貨。
SHIPPED 已出貨。
DELIVERED 已送達。
OUT_OF_STOCK 缺貨中。
IN_PREPARATION 「IN_PREPARATION」在不同情境中可能有不同的意義。對於 FOOD 訂餐,您可以烹調食物。以零售通路來說,這類產品可能是包裝中的商品。
CREATED 訂單已建立。
CONFIRMED 商家已確認訂單。
REJECTED 商家拒絕了訂單或明細項目。
RETURNED 使用者退回商品。
CANCELLED 使用者已取消訂單或委刊項。
CHANGE_REQUESTED 使用者已要求變更訂單,整合商正在處理這項變更。處理要求後,訂單應移至其他狀態。

PurchaseType

購買類別。

列舉
PURCHASE_TYPE_UNSPECIFIED 不明的值。
RETAIL 包括實體商品。
FOOD 包括訂餐。
GROCERY 購買雜貨。
MOBILE_RECHARGE 預付行動儲值費用。

MerchantUnitMeasure

商家計價單位。

JSON 表示法
{
  "measure": number,
  "unit": enum (Unit)
}
欄位
measure

number

值:範例 1.2。

unit

enum (Unit)

單位:POUND 範例,GRAM。

單位

列舉
UNIT_UNSPECIFIED 未指定單位。
MILLIGRAM 毫克。
GRAM 文法。
KILOGRAM 公斤
OUNCE
POUND 英鎊。

PurchaseReturnsInfo

傳回與訂單或特定委刊項相關聯的資訊。

JSON 表示法
{
  "isReturnable": boolean,
  "daysToReturn": number,
  "policyUrl": string
}
欄位
isReturnable

boolean

如果為 true,則允許傳回。

daysToReturn

number

退貨期限為 5 天內。

policyUrl

string

退貨政策連結。

PurchaseFulfillmentInfo

與訂購單或特定明細項目相關聯的出貨資訊。

JSON 表示法
{
  "id": string,
  "fulfillmentType": enum (Type),
  "expectedFulfillmentTime": {
    object (Time)
  },
  "expectedPreparationTime": {
    object (Time)
  },
  "location": {
    object (Location)
  },
  "expireTime": string,
  "price": {
    object (PriceAttribute)
  },
  "fulfillmentContact": {
    object (UserInfo)
  },
  "shippingMethodName": string,
  "storeCode": string,
  "pickupInfo": {
    object (PickupInfo)
  }
}
欄位
id

string

這個服務選項的專屬 ID。

fulfillmentType

enum (Type)

必要:執行要求類型。

expectedFulfillmentTime

object (Time)

如已指定時間範圍,則顯示的時間範圍,如指定 ETA。預計送達或取貨時間。

expectedPreparationTime

object (Time)

如已指定時間範圍,則顯示的時間範圍,如指定 ETA。預期的準備時間。一次性選項。

location

object (Location)

取貨或送貨地點。

expireTime

string (Timestamp format)

這個執行要求選項的到期時間。

RFC3339 世界標準時間「Zulu」格式的時間戳記,精確度達奈秒單位,範例:"2014-10-02T15:01:23.045123456Z"

price

object (PriceAttribute)

此選項的費用。

fulfillmentContact

object (UserInfo)

此執行要求的使用者聯絡人。

shippingMethodName

string

使用者所選運送方式的名稱。

storeCode

string

位置的 StoreCode。例如:Walmart 是商家,storeCode 則是出貨地點的 Walmart 商店。https://support.google.com/business/answer/3370250?ref_topic=4596653

pickupInfo

object (PickupInfo)

有關如何挑選訂單的其他資訊。只有在執行要求類型為 PICKUP 時,才能使用這個欄位。

類型

出貨類型。

列舉
TYPE_UNSPECIFIED 未指定類型。
DELIVERY 這筆訂單即將送達。
PICKUP 此訂單尚未取貨。

時間

時間結構代表向使用者顯示訂單時要使用的事件時間。

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

string

代表訂單事件時間,例如預約時間和運送時間等。可以輸入時間長度 (開始和結束時間),或是日期、日期和時間等。如要瞭解所有支援的格式,請參閱 https://en.wikipedia.org/wiki/ISO_8601

PickupInfo

訂單取貨方式的詳細資料。包括取貨類型等詳細資料,以及各類型附加的其他中繼資料 (如有)。

JSON 表示法
{
  "pickupType": enum (PickupType),
  "curbsideInfo": {
    object (CurbsideInfo)
  },
  "checkInInfo": [
    {
      object (CheckInInfo)
    }
  ]
}
欄位
pickupType

enum (PickupType)

取貨方式,例如 INStore、CURBSIDE 等。

curbsideInfo

object (CurbsideInfo)

店外資訊的詳細資料。如果 pickupType 不是「CURBSIDE」,系統會忽略這個欄位。

checkInInfo[]

object (CheckInInfo)

合作夥伴支援辦理入住手續的各種方法清單。

PickupType

支援的取貨類型清單。

列舉
UNSPECIFIED 未指定取貨類型。
INSTORE 到餐廳取貨。
CURBSIDE 將車輛停妥於餐廳以外的指定地點,有人會到該處提供餐點。

CurbsideInfo

店外訂單的處理方式詳細說明。

JSON 表示法
{
  "curbsideFulfillmentType": enum (CurbsideFulfillmentType),
  "userVehicle": {
    object (Vehicle)
  }
}
欄位
curbsideFulfillmentType

enum (CurbsideFulfillmentType)

合作夥伴需要提供額外資訊,才能處理店外取貨訂單。視所選的執行要求類型而定,系統會向使用者收集相應的詳細資料。

userVehicle

object (Vehicle)

使用者下單的車輛詳細資料。

CurbsideFulfillmentType

店外交車類型可能的值。

列舉
UNSPECIFIED 未指定店外執行要求類型。
VEHICLE_DETAIL 需要車輛詳細資料才能提供店外取貨服務。

車輛

車輛詳細資料

JSON 表示法
{
  "make": string,
  "model": string,
  "licensePlate": string,
  "colorName": string,
  "image": {
    object (Image)
  }
}
欄位
make

string

汽車廠牌 (例如「Honda」)。系統會向使用者顯示這項內容,且必須進行本地化。這是必要項目。

model

string

車輛型式 (例如「汽油」)。系統會向使用者顯示這項內容,且必須進行本地化。這是必要項目。

licensePlate

string

車牌號碼 (例如「1ABC234」)。這是必要項目。

colorName

string

車輛顏色名稱,例如黑色選填。

image

object (Image)

車輛相片的網址。相片會以約 256x256 像素顯示。必須是 jpg 或 png。(選用)

CheckInInfo

合作夥伴必須支援 Checkin 方法所需的中繼資料。

JSON 表示法
{
  "checkInType": enum (CheckInType)
}
欄位
checkInType

enum (CheckInType)

傳送登記操作說明的方法。

CheckInType

傳送簽到指示的各種方法。

列舉
CHECK_IN_TYPE_UNSPECIFIED 不明的值。
EMAIL 系統會透過電子郵件傳送 CheckIn 資訊。
SMS 將會透過簡訊傳送 CheckIn 資訊。

ItemOption

代表外掛程式或子作品。

JSON 表示法
{
  "id": string,
  "name": string,
  "prices": [
    {
      object (PriceAttribute)
    }
  ],
  "note": string,
  "quantity": number,
  "productId": string,
  "subOptions": [
    {
      object (ItemOption)
    }
  ]
}
欄位
id

string

關於項目的選項,則專屬項目 ID。

name

string

選項名稱。

prices[]

object (PriceAttribute)

選項總價。

note

string

選項相關注意事項。

quantity

number

適用於項目、數量的選項。

productId

string

與這個選項相關聯的產品或優惠 ID。

subOptions[]

object (ItemOption)

定義其他巢狀子選項。

ProductDetails

產品詳細資料。

JSON 表示法
{
  "productId": string,
  "gtin": string,
  "plu": string,
  "productType": string,
  "productAttributes": {
    string: string,
    ...
  }
}
欄位
productId

string

與這個委刊項相關聯的產品或優惠 ID。

gtin

string

產品的全球交易品項識別碼。如果 Merchant Center 中沒有 OfferId,這個做法就相當實用。(選用)

plu

string

價格查詢代碼 (通常稱為 PLU 代碼、PLU 號碼、PLU、產生的代碼或製作標籤) 是一組編號,可用來識別雜貨店和超市銷售的批發農產品。

productType

string

商家定義的產品類別。例如「首頁 > 雜貨店 > 奶油 > 牛奶 > 全杯牛奶」

productAttributes

map (key: string, value: string)

商家提供的產品詳細資料,例如 { "allergen": "peanut" }。如果 Merchant Center 中沒有 OfferId,這個做法就相當實用。選用。

這個物件中包含 "key": value 組合的清單,例如:{ "name": "wrench", "mass": "1.3kg", "count": "3" }.

ReservationItemExtension

餐廳、剪髮等預訂訂單的委刊項內容,下一個 ID:15。

JSON 表示法
{
  "status": enum (ReservationStatus),
  "userVisibleStatusLabel": string,
  "type": enum (ReservationType),
  "reservationTime": {
    object (Time)
  },
  "userAcceptableTimeRange": {
    object (Time)
  },
  "confirmationCode": string,
  "partySize": number,
  "staffFacilitators": [
    {
      object (StaffFacilitator)
    }
  ],
  "location": {
    object (Location)
  },
  "extension": {
    "@type": string,
    field1: ...,
    ...
  }
}
欄位
status

enum (ReservationStatus)

必要:預訂狀態。

userVisibleStatusLabel

string

必要:使用者能夠看見狀態的標籤/字串。長度上限為 50 個半形字元。

type

enum (ReservationType)

保留項目類型。如果沒有任何類型選項適用,則可取消設定。

reservationTime

object (Time)

安排服務/活動進行的時間。可以是時間範圍、日期或確切日期時間。

userAcceptableTimeRange

object (Time)

使用者可以接受的時間範圍。

confirmationCode

string

此保留項目的確認代碼。

partySize

number

人數。

staffFacilitators[]

object (StaffFacilitator)

準備預訂行程的職員講師。例如:髮型師。

location

object (Location)

服務/事件的位置。

extension

object

商家與 Google 之間交換的任何額外欄位。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如:{ "id": 1234, "@type": "types.example.com/standard/id" }.

ReservationStatus

預訂狀態。

列舉
RESERVATION_STATUS_UNSPECIFIED 未指定的狀態。
PENDING 保留項目尚待處理。
CONFIRMED 已確認預約。
CANCELLED 使用者已取消預訂。
FULFILLED 預留完成。
CHANGE_REQUESTED 已要求變更預訂
REJECTED 預訂者已過期或遭到整合者拒絕。

ReservationType

保留項目類型。

列舉
RESERVATION_TYPE_UNSPECIFIED 未指定的類型。
RESTAURANT 你的餐廳訂位。
HAIRDRESSER 預約美髮店。

StaffFacilitator

服務人員的相關資訊。

JSON 表示法
{
  "name": string,
  "image": {
    object (Image)
  }
}
欄位
name

string

工作人員的講師姓名。例如:「王大明」

image

object (Image)

表演者的圖片。

PaymentData

與訂單相關的付款資料。

JSON 表示法
{
  "paymentResult": {
    object (PaymentResult)
  },
  "paymentInfo": {
    object (PaymentInfo)
  }
}
欄位
paymentResult

object (PaymentResult)

整合商用來完成交易的付款方式。如果結帳體驗是由 Actions-on-Google 管理,Actions on Google 就會填入這個欄位。

paymentInfo

object (PaymentInfo)

與面向使用者互動的訂單相關的付款資訊。

PaymentResult

整合商用來完成交易的付款方式。

JSON 表示法
{

  // Union field result can be only one of the following:
  "googlePaymentData": string,
  "merchantPaymentMethodId": string
  // End of list of possible types for union field result.
}
欄位
聯集欄位 result。提供 Google 付款資料或商家付款方式。result 只能是下列其中一項:
googlePaymentData

string

Google 提供的付款方式資料。如果 Google 支援的付款處理方列為 Google 支援的付款處理方,請前往以下網址:https://developers.google.com/pay/api/ 前往付款處理方連結,瞭解詳情。如果不是,請參閱下列酬載詳細資料:https://developers.google.com/pay/api/payment-data-cryptography

merchantPaymentMethodId

string

使用者選擇商家/動作提供的付款方式。

PaymentInfo

所下訂單的付款資訊。這個 Proto 會擷取適用於使用者互動的資訊。

JSON 表示法
{
  "paymentMethodDisplayInfo": {
    object (PaymentMethodDisplayInfo)
  },
  "paymentMethodProvenance": enum (PaymentMethodProvenance)
}
欄位
paymentMethodDisplayInfo

object (PaymentMethodDisplayInfo)

交易所用付款方式的顯示資訊。

paymentMethodProvenance

enum (PaymentMethodProvenance)

交易所用付款方式的證明。使用者可能已向 Google 和商家註冊相同的付款方式。

PaymentMethodDisplayInfo

整合商用來完成交易的付款方式。

JSON 表示法
{
  "paymentType": enum (PaymentType),
  "paymentMethodDisplayName": string,
  "paymentMethodVoiceName": string
}
欄位
paymentType

enum (PaymentType)

付款的類型。

paymentMethodDisplayName

string

付款方式向使用者顯示的名稱。例如 VISA **** 1234 支票帳戶 **** 5678

paymentMethodVoiceName

string

針對僅限語音助理裝置,向使用者顯示的付款方式名稱。例如:「簽證末四碼二三四」或「檢查末四碼五七八的簽證」。注意:這是語音最佳化字串,用於純語音助理裝置,而不是 paymentMethodDisplayName。如未設定此字串,系統會改為向使用者讀出 paymentMethodDisplayName。

PaymentType

PaymentType 表示商家提供的付款方式所使用的付款方式。此外,動作也必須為付款方式提供顯示名稱。

列舉
PAYMENT_TYPE_UNSPECIFIED 未指定的付款方式。
PAYMENT_CARD 信用卡/簽帳金融卡或預付卡。
BANK 付款方式為銀行帳戶。
LOYALTY_PROGRAM 付款方式屬於會員方案。
CASH 付款方式為現金。
GIFT_CARD 付款方式為禮物卡。
WALLET 第三方錢包,例如 PayPal

PaymentMethodProvenance

代表交易使用的付款方式來源。

列舉
PAYMENT_METHOD_PROVENANCE_UNSPECIFIED 未指定來源。
PAYMENT_METHOD_PROVENANCE_GOOGLE 來源就是 Google。
PAYMENT_METHOD_PROVENANCE_MERCHANT 來源是商家。

宣傳

新增至購物車的促銷活動/優惠。

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

string

必填:套用至這項優惠的優待券代碼。

PurchaseOrderExtension

適用於採購產業的訂單延長期限。除非在委刊項中覆寫這些屬性,否則這些屬性適用於所有委刊項。

JSON 表示法
{
  "status": enum (PurchaseStatus),
  "userVisibleStatusLabel": string,
  "type": enum (PurchaseType),
  "returnsInfo": {
    object (PurchaseReturnsInfo)
  },
  "fulfillmentInfo": {
    object (PurchaseFulfillmentInfo)
  },
  "extension": {
    "@type": string,
    field1: ...,
    ...
  },
  "purchaseLocationType": enum (PurchaseLocationType),
  "errors": [
    {
      object (PurchaseError)
    }
  ]
}
欄位
status

enum (PurchaseStatus)

必填:訂單的整體狀態。

userVisibleStatusLabel

string

使用者顯示的狀態標籤/字串。長度上限為 50 個半形字元。

type

enum (PurchaseType)

必填:購買類型。

returnsInfo

object (PurchaseReturnsInfo)

訂單的退貨資訊。

fulfillmentInfo

object (PurchaseFulfillmentInfo)

訂單的出貨資訊。

extension

object

商家與 Google 之間交換的任何額外欄位。

包含任意類型欄位的物件。額外的 "@type" 欄位則包含能辨識類型的 URI。例如:{ "id": 1234, "@type": "types.example.com/standard/id" }.

purchaseLocationType

enum (PurchaseLocationType)

購買位置 (店內 / 線上)

errors[]

object (PurchaseError)

選填:因為這筆訂單而遭到拒絕的錯誤。

PurchaseLocationType

購買商品的位置類型。

列舉
UNSPECIFIED_LOCATION 不明的值。
ONLINE_PURCHASE 所有在線上購買的商品。
INSTORE_PURCHASE 所有店內購物交易。

PurchaseError

訂購單可遭拒的錯誤。

JSON 表示法
{
  "type": enum (ErrorType),
  "description": string,
  "entityId": string,
  "updatedPrice": {
    object (PriceAttribute)
  },
  "availableQuantity": number
}
欄位
type

enum (ErrorType)

必填:這代表商家拒絕訂單的詳細原因。

description

string

其他錯誤說明。

entityId

string

與錯誤對應的實體 ID。範例可對應到 LineItemId / ItemOptionId。

updatedPrice

object (PriceAttribute)

與 PRICE_CHANGED / INCORRECT_PRICE 錯誤類型相關。

availableQuantity

number

現貨數量。適用於 AVAILABILITY_CHANGED。

ErrorType

可能的錯誤類型。

列舉
ERROR_TYPE_UNSPECIFIED 發生不明錯誤
NOT_FOUND 找不到實體,可能是項目、FulfillmentOption、promotion。必須提供實體 ID。
INVALID 實體資料無效,可以是「Item」、「FulfillmentOption」和「promotion」。必須提供實體 ID。
AVAILABILITY_CHANGED 商品無法使用,或商品不足而無法履行要求。必須提供實體 ID。
PRICE_CHANGED 商品價格與商品實體中的價格不同。必須提供實體 ID 和更新後的價格。
INCORRECT_PRICE 「費用」中的價格錯誤。必須提供實體 ID 和更新後的價格。
REQUIREMENTS_NOT_MET 未達到訂單接受的限制 - 購物車商品數量下限等
TOO_LATE FulfillmentOption 已過期。
NO_CAPACITY 沒有可用的服務容量。
INELIGIBLE 使用者不符合下單資格 (已列入黑名單)。
OUT_OF_SERVICE_AREA 因邊界規則等因素而無法送達指定的地址。
CLOSED 餐廳在訂餐時不營業。
PROMO_NOT_APPLICABLE 一般錯誤代碼,用於找出無法套用促銷代碼的所有情況 (如果下方選項皆不適用)。新增促銷代碼做為實體 ID。
PROMO_NOT_RECOGNIZED 合作夥伴無法辨識優待券代碼。新增促銷代碼做為實體 ID。
PROMO_EXPIRED 促銷活動已過期,因此無法套用。新增促銷代碼做為實體 ID。
PROMO_USER_INELIGIBLE 目前的使用者不符合此優待券的使用資格。新增促銷代碼做為實體 ID。
PROMO_ORDER_INELIGIBLE 目前的訂單不適用這張優待券。新增促銷代碼做為實體 ID。
UNAVAILABLE_SLOT 無法預訂預訂的時段。
FAILED_PRECONDITION 未達成訂單接受的限制 - 購物車商品數量下限等
PAYMENT_DECLINED 付款無效。
MERCHANT_UNREACHABLE 無法聯絡商家。如果合作夥伴是集結網站,但無法聯絡商家,這項功能會派上用場。

TicketOrderExtension

訂購電影、體育等票券訂單內容。

JSON 表示法
{
  "ticketEvent": {
    object (TicketEvent)
  }
}
欄位
ticketEvent

object (TicketEvent)

事件會套用到所有委刊項票券。

TicketEvent

代表單一事件。

JSON 表示法
{
  "type": enum (Type),
  "name": string,
  "description": string,
  "url": string,
  "location": {
    object (Location)
  },
  "eventCharacters": [
    {
      object (EventCharacter)
    }
  ],
  "startDate": {
    object (Time)
  },
  "endDate": {
    object (Time)
  },
  "doorTime": {
    object (Time)
  }
}
欄位
type

enum (Type)

必填:票券活動的類型,例如電影、演唱會。

name

string

必填:活動名稱。舉例來說,如果事件是電影,則應提供電影名稱。

description

string

事件的說明。

url

string

活動資訊的網址。

location

object (Location)

活動舉辦地點或機構所在地點。

eventCharacters[]

object (EventCharacter)

與這個事件相關的角色。例如電影活動的導演或演員,或演唱會的表演者等。

startDate

object (Time)

開始時間。

endDate

object (Time)

結束時間。

doorTime

object (Time)

進入時間,可能與活動開始時間不同,例如:活動將於上午 9 點開始,但進入時間是上午 8:30。

類型

事件的類型。

列舉
EVENT_TYPE_UNKNOWN 不明的事件類型。
MOVIE 電影。
CONCERT 音樂會/演唱會。
SPORTS 運動賽事。

EventCharacter

一個活動角色,例如發起人、表演者等。

JSON 表示法
{
  "type": enum (Type),
  "name": string,
  "image": {
    object (Image)
  }
}
欄位
type

enum (Type)

事件角色類型,例如演員或導演。

name

string

字元名稱。

image

object (Image)

角色的圖片。

類型

字元類型。

列舉
TYPE_UNKNOWN 類型不明。
ACTOR 執行者。
PERFORMER 演出者。
DIRECTOR 導演。
ORGANIZER 發起人: