權限

您可以使用動作中的權限，要求使用者提供個人資料，以便完成要求。舉例來說，餐點外送動作可能會使用裝置位置存取權來詢問使用者位置資訊。

為動作新增權限時，Google 助理會顯示一個標準的一致性介面，用於要求使用者授予權限，以便向動作提供資訊。

可用權限

你可以要求下列動作要求下列權限：

  • DEVICE_PRECISE_LOCATION：要求使用者精確的裝置位置 (座標和街道地址)。
  • DEVICE_COARSE_LOCATION：要求使用者的概略裝置位置 (郵遞區號和城市)。

設定權限

如要設定動作的權限，您可以為場景新增運算單元類型。再針對需要求的資料權限設定運算單元。

新增權限運算單元類型

您可以利用 actions.type.Permission 版位類型，讓動作取得使用者資訊。

如要設定這個運算單元類型，請按照下列步驟操作：

  1. 前往動作控制台，然後選取或建立專案。
  2. 按一下頂端選單中的「開發」。
  3. 在「情境」下方，按一下您要新增權限流程的情境。
  4. 在情境的「版位填滿」部分下方，按一下「+」新增版位。

  5. 在「Select type」(選取類型) 下拉式選單中，選取 actions.type.Permission 運算單元類型。

  6. 在「Enter slot name」(輸入運算單元名稱) 欄位中，為運算單元命名。

  7. 啟用自訂運算單元值寫入功能，將結果寫入工作階段參數。

設定運算單元

您現在可以提供結構定義字串和授予設定運算單元的權限清單。「結構定義字串」是的原因，說明您要求使用者提供資訊的原因，並會在使用者被授權授予權限時向使用者顯示。

您可以在「Configure slot」(設定運算單元) 區段中設定結構定義字串和權限，如以下螢幕截圖所示：

下列程式碼片段顯示了運算單元設定範例：

{
  "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValueSpec",
  "context": "Context string",
  "permissions": ["DEVICE_PRECISE_LOCATION"]
}

向使用者顯示的提示訊息會以 "$context_string" 的形式呈現，我需要從 Google 取得你目前的位置。請問這樣可以嗎？」

您可以使用權限代碼取得下列使用者資訊：

權限 說明
DEVICE_PRECISE_LOCATION 精確裝置位置 (座標和街道地址)
DEVICE_COARSE_LOCATION 約略裝置位置 (郵遞區號和城市)

取得權限結果

以下各節說明如何查看權限狀態，並閱讀使用者授予權限時的相關資訊。

查看權限狀態

使用者授予權限時，產生的狀態會寫入與運算單元關聯的工作階段參數。

您可以在情境中檢查 session.params.<slot_name>.permissionStatus 的值，藉此檢查權限狀態。

如要查看權限運算單元的狀態，請按照下列步驟操作：

  1. 前往動作控制台，然後按一下頂端選單中的「開發」。
  2. 在「情境」下方，按一下含有權限版位的場景。
  3. 在情境的「Condition」(條件) 區段下方，按一下「+」來新增條件。

  4. 輸入下列條件來檢查權限狀態 (其中 <slot_name> 是您在版位中設定工作階段參數的名稱)：

    scene.slots.status == "FINAL" && (session.params.<slot_name>.permissionStatus == "PERMISSION_GRANTED" || session.params.<slot_name>.permissionStatus == "ALREADY_GRANTED")

  5. 在情境的「Condition」(條件) 區段下方，按一下「+」來新增條件。

  6. 輸入下列條件，以處理使用者不同意分享個人資訊的情況：

    scene.slots.status == "FINAL"

  7. 在情境的「Condition」(條件) 區段下方，按一下「+」來新增條件。

  8. 輸入下列條件，以處理使用者已經授予權限的情況，不需要再詢問：

    "DEVICE_PRECISE_LOCATION" in user.permissions

讀取使用者資訊

如果使用者授予權限，使用者後續請求中便會提供使用者資訊。

在下方的程式碼片段中，您可以在 device.currentLocation 的要求下方，查看向 Webhook 發出的裝置位置資訊：

要求 JSON 
  {
      "handler": {
        "name": "handler"
      },
      "intent": {
        "name": "",
        "params": {
          "deviceLoc": {
            "original": "",
            "resolved": {
              "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue",
              "permissionStatus": "PERMISSION_GRANTED",
              "grantedPermissions": [
                "DEVICE_PRECISE_LOCATION"
              ]
            }
          }
        },
        "query": "Yes"
      },
      "scene": {
        "name": "Scene",
        "slotFillingStatus": "FINAL",
        "slots": {
          "deviceLoc": {
            "mode": "REQUIRED",
            "status": "SLOT_UNSPECIFIED",
            "value": {
              "grantedPermissions": [
                "DEVICE_PRECISE_LOCATION"
              ],
              "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue",
              "permissionStatus": "PERMISSION_GRANTED"
            },
            "updated": true
          }
        },
        "next": {
          "name": "actions.scene.END_CONVERSATION"
        }
      },
      "session": {
        "id": "session_id",
        "params": {
          "deviceLoc": {
            "grantedPermissions": [
              "DEVICE_PRECISE_LOCATION"
            ],
            "permissionStatus": "PERMISSION_GRANTED",
            "@type": "type.googleapis.com/google.actions.conversation.v3.PermissionValue"
          }
        },
        "typeOverrides": [],
        "languageCode": ""
      },
      "user": {
        "locale": "en-US",
        "params": {},
        "accountLinkingStatus": "ACCOUNT_LINKING_STATUS_UNSPECIFIED",
        "verificationStatus": "VERIFIED",
        "packageEntitlements": [],
        "permissions": [
          "DEVICE_PRECISE_LOCATION"
        ],
        "lastSeenTime": "2021-02-08T20:43:47Z"
      },
      "home": {
        "params": {}
      },
      "device": {
        "capabilities": [
          "SPEECH",
          "RICH_RESPONSE",
          "LONG_FORM_AUDIO"
        ],
        "currentLocation": {
          "coordinates": {
            "latitude": 37.422,
            "longitude": -122.084
          },
          "postalAddress": {
            "revision": 0,
            "regionCode": "US",
            "languageCode": "en",
            "postalCode": "94043",
            "sortingCode": "",
            "administrativeArea": "California",
            "locality": "Mountain View",
            "sublocality": "",
            "addressLines": ["1600 Amphitheatre Parkway"],
            "recipients": [],
            "organization": ""
          }
        }
      }
    }

如要進一步瞭解位置類型的結構定義，請參閱 Location 參考資料。

您可以存取 Webhook 要求中的資訊，如以下程式碼片段所示：

Webhook 
  app.handle('handler', (conv) => {
    let location = conv.device.currentLocation;
    conv.add(`Your postal code is ${location.postalCode}`);
  });

在提示訊息中使用權限

您也可以在靜態提示中參照權限。舉例來說，針對裝置位置，您可以使用 $device.currentLocation.coordinates.* 和 $device.currentLocation.postalAddress.*。下列程式碼片段說明如何在提示中參照使用者的城市：

candidates:
  - first_simple:
      variants:
        - speech: >-
            There are no events scheduled tomorrow in the city of $device.currentLocation.postalAddress.locality.