AppRequest

AppRequest 是 Google 助理為了與動作互動而向執行要求傳送的要求。此 API 版本會在 HTTP 標頭中指定。若是 API 版本 1,標頭包含:Google-Assistant-API-Version: v1。如果是 API 第 2 版,標頭會包含:Google-actions-API-Version: 2。如需實際在 Google 上的動作使用範例,請參閱 https://developers.google.com/assistant/df-asdk/reference/conversation-webhook-json

JSON 表示法
{
  "user": {
    object (User)
  },
  "device": {
    object (Device)
  },
  "surface": {
    object (Surface)
  },
  "conversation": {
    object (Conversation)
  },
  "inputs": [
    {
      object (Input)
    }
  ],
  "isInSandbox": boolean,
  "availableSurfaces": [
    {
      object (Surface)
    }
  ]
}
欄位
user

object (User)

發起對話的使用者。

device

object (Device)

使用者用於與動作互動的裝置相關資訊。

surface

object (Surface)

使用者互動介面的相關資訊,例如:輸出音訊或螢幕。

conversation

object (Conversation)

保留工作階段資料,例如對話 ID 和對話符記。

inputs[]

object (Input)

與動作指定的預期輸入內容相對應的輸入項目清單。針對初始對話觸發條件,輸入內容含有使用者如何觸發對話的資訊。

isInSandbox

boolean

指出是否要在沙箱模式中處理要求。

availableSurfaces[]

object (Surface)

可用於交叉表面轉換的介面。

使用者

JSON 表示法
{
  "idToken": string,
  "profile": {
    object (UserProfile)
  },
  "accessToken": string,
  "permissions": [
    enum (Permission)
  ],
  "locale": string,
  "lastSeen": string,
  "userStorage": string,
  "packageEntitlements": [
    {
      object (PackageEntitlement)
    }
  ],
  "userVerificationStatus": enum (UserVerificationStatus)
}
欄位
idToken

string

代表使用者身分的符記這是包含編碼設定檔的 Json 網路權杖。(定義請見 https://developers.google.com/identity/protocols/OpenIDConnect#obtainuserinfo)。

profile

object (UserProfile)

使用者的相關資訊。部分欄位只有在使用者授予該動作提供這項資訊的權限時才會顯示。

accessToken

string

用來在系統中識別使用者的 OAuth2 權杖。只有在使用者連結自己的帳戶時,才能使用此設定。

permissions[]

enum (Permission)

包含使用者授予這項動作的權限。

locale

string

提出要求的使用者的主要語言代碼設定。遵循 IETF BCP-47 語言代碼 http://www.rfc-editor.org/rfc/bcp/bcp47.txt,但不包含指令碼子標記。

lastSeen

string (Timestamp format)

上次與這位使用者互動的時間戳記。如果使用者先前未曾與代理程式互動,系統就會省略這個欄位。

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

userStorage

string

應用程式提供的不透明憑證,固定在特定使用者對話中。字串大小上限為 1 萬個字元。

packageEntitlements[]

object (PackageEntitlement)

動作套件中列出的每個套件名稱的使用者授權清單 (如果有的話)。

userVerificationStatus

enum (UserVerificationStatus)

指出使用者的驗證狀態。

UserProfile

包含使用者的個人資訊。只有在使用者為特定欄位授予「動作」權限時,系統才會在欄位填入資料。

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

string

使用者在 Google 帳戶中指定的全名。必須具備 NAME 權限。

givenName

string

使用者在 Google 帳戶中指定的名字。必須具備 NAME 權限。

familyName

string

使用者在 Google 帳戶中指定的姓氏。請注意,這個欄位可以留空。必須具備 NAME 權限。

PackageEntitlement

與套件名稱相關的授權清單

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

string

必須與動作套件中的套件名稱相符

entitlements[]

object (Entitlement)

特定應用程式的授權清單

授權

定義使用者的數位授權。可能的授權類型:付費應用程式、應用程式內購、應用程式內訂閱項目。

JSON 表示法
{
  "sku": string,
  "skuType": enum (SkuType),
  "inAppDetails": {
    object (SignedData)
  }
}
欄位
sku

string

產品 SKU。付費應用程式的套件名稱,為應用程式內購項目和應用程式內訂閱項目的 Finsky Docid 字首。在 Play InApp Billing API 中比對 getSku()。

skuType

enum (SkuType)

inAppDetails

object (SignedData)

僅會顯示於應用程式內購和應用程式內訂閱。

SignedData

JSON 表示法
{
  "inAppPurchaseData": {
    object
  },
  "inAppDataSignature": string
}
欄位
inAppPurchaseData

object (Struct format)

比對 getPurchases() 方法的 INAPP_PURCHASE_DATA。包含 JSON 格式的所有應用程式內購資料。詳情請參閱 https://developer.android.com/google/play/billing/billing_reference.html 的表格 6。

inAppDataSignature

string

比對 Play InApp Billing API 中來自 getPurchases() 方法的 IN_APP_DATA_SIGNATURE。

裝置

使用者用於與動作互動的裝置相關資訊。

JSON 表示法
{
  "location": {
    object (Location)
  }
}
欄位
location

object (Location)

代表裝置實際位置,例如經緯度和格式化地址。必須具備 DEVICE_COARSE_LOCATIONDEVICE_PRECISE_LOCATION 權限。

Surface

使用者進行互動的 Google 助理用戶端專屬資訊。同一台裝置上可能有多個 Google 助理介面,系統將透過途徑與裝置區別。

JSON 表示法
{
  "capabilities": [
    {
      object (Capability)
    }
  ]
}
欄位
capabilities[]

object (Capability)

要求時介面支援的功能清單,例如actions.capability.AUDIO_OUTPUT

功能

代表途徑支援的功能單位。

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

string

功能的名稱,例如:actions.capability.AUDIO_OUTPUT

對話

JSON 表示法
{
  "conversationId": string,
  "type": enum (ConversationType),
  "conversationToken": string
}
欄位
conversationId

string

多輪對話的專屬 ID。為第一回合指派。之後對話將維持不變,直到對話終止為止。

type

enum (ConversationType)

type 表示對話在生命週期中的狀態。

conversationToken

string

動作在最後一個對話回合中指定的不透明符記。動作可用於追蹤對話或儲存對話相關資料。

輸入

JSON 表示法
{
  "rawInputs": [
    {
      object (RawInput)
    }
  ],
  "intent": string,
  "arguments": [
    {
      object (Argument)
    }
  ]
}
欄位
rawInputs[]

object (RawInput)

從每個對話回合的原始輸入內容轉錄內容。要對 Google 執行動作時,可能需要多次切換對話,才能提供某些類型的輸入動作。

intent

string

用於表示使用者的意圖。對第一回合的對話來說,意圖會參照該動作的觸發意圖。在後續對話回合中,意圖是 Google 意圖的常見動作 (開頭為「actions」)。舉例來說,如果預期的輸入內容是 actions.intent.OPTION,那麼如果 Google 助理能夠滿足該意圖,這裡指定的意圖就會是 actions.intent.OPTION,但如果使用者提供其他資訊,則會是 actions.intent.TEXT。詳情請參閱 https://developers.google.com/assistant/df-asdk/reference/intents

arguments[]

object (Argument)

針對動作要求的輸入提供所提供的引數值清單。

RawInput

JSON 表示法
{
  "inputType": enum (InputType),

  // Union field input can be only one of the following:
  "query": string,
  "url": string
  // End of list of possible types for union field input.
}
欄位
inputType

enum (InputType)

指出使用者如何提供輸入內容:輸入的回應、語音回應、未指定等。

聯集欄位 input。實際輸入值 input 只能採用下列其中一種設定:
query

string

使用者輸入或語音輸入的內容。

url

string

觸發網址。