AppRequest

AppRequest 是 Google 助理為了與動作互動而向執行要求送出的要求。您可以在 HTTP 標頭中指定 API 版本。針對 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)

比對 INAPP_PURCHASE_DATA 與 getPurchases() 方法。以 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 權限。

介面

與使用者互動的 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

觸發網址。