本頁面由 Cloud Translation API 翻譯而成。

JSON Web Token

JSON Web Token (JWT) 是一種開放式網路標準，用於驗證及授權用戶端與伺服器之間的資訊交換。應用程式使用者首次使用適當角色憑證登入時，伺服器會建立並傳回經過編碼及數位簽章的 JWT，供後續要求使用。這個程序會驗證使用者身分，並根據帳戶角色授權使用者存取路徑、服務和資源。

從低信任度環境 (智慧型手機和瀏覽器) 呼叫 API 方法時，Fleet Engine 必須使用 JSON Web Token (JWT)。

JWT 會在伺服器上產生、簽署、加密，並傳遞至用戶端，供後續伺服器互動使用，直到 JWT 過期或失效為止。

重要詳細資料

與 API 金鑰不同，JWT 的效期較短，且僅限角色授權執行的作業。如要進一步瞭解 JWT，請參閱維基百科的「JSON Web Token」。如要進一步瞭解存取角色，請參閱本指南中的「服務帳戶角色」。

JWT 元素

JWT 包含標頭和聲明部分。標頭部分包含從服務帳戶取得的私密金鑰和加密演算法等資訊。聲明部分包含 JWT 的建立時間、存留時間、JWT 聲明可存取的服務，以及其他授權資訊 (例如運送車輛 ID)，可限制存取範圍。

下表提供 JWT 欄位的一般說明，以及在 Fleet Engine Cloud 專案中尋找這些欄位值的具體資訊。

JWT 標頭欄位
欄位	說明
alg	要使用的演算法。`RS256`。
typ	權杖類型。`JWT`。
兒童	服務帳戶的私密金鑰 ID。您可以在服務帳戶 JSON 檔案的 `private_key_id` 欄位中找到這個值。請務必使用具備正確權限等級的服務帳戶金鑰。

JWT 憑證附加資訊欄位
欄位	說明
iss	服務帳戶的電子郵件地址，位於服務帳戶 JSON 檔案的 `client_email` 欄位中。
替補球員	服務帳戶的電子郵件地址，位於服務帳戶 JSON 檔案的 `client_email` 欄位中。
aud	服務帳戶的 `SERVICE_NAME`，在本例中為 `https://fleetengine.googleapis.com/`
iat	JWT 的建立時間戳記，以自 00:00:00 `UTC, January 1, 1970` 起經過的秒數表示。允許 10 分鐘的偏移。如果時間戳記太久以前或太久以後，伺服器可能會回報錯誤。
exp	JWT 的到期時間戳記，以自 `00:00:00 UTC, January 1, 1970` 起經過的秒數表示。如果時間戳記超過一小時，要求就會失敗。
授權	視用途而定，可能包含 `deliveryvehicleid`、`trackingid`、`taskid` 或 `taskids`。如要指定 taskid，授權範圍必須是陣列，且格式如下： `"taskids": ["task_id_one","task_id_two"]` 或 `"taskids": ["*"]`

Fleet Engine 會使用私有聲明。使用私有聲明可確保只有授權用戶端能存取自己的資料。

舉例來說，當伺服器為駕駛人的行動裝置核發 JSON 網頁權杖時，應包含 vehicleid 聲明或 deliveryvehicleid 聲明，並以該駕駛人的車輛 ID 做為值。然後，視駕駛員角色而定，JWT 只會啟用特定車輛 ID 的存取權，不會啟用任何其他任意車輛 ID。

Fleet Engine 使用下列私人聲明：

vehicleid：
- 無論是行程或車輛作業，Driver SDK 一律會使用這項聲明。Fleet Engine 後端會先確認車輛與要求行程相關聯，再進行修改。
- JWT 可涵蓋車輛和行程作業，即使並非必要，也能簡化 JWT 簽署實作程序。
tripid：
- Consumer SDK 一律會使用這項聲明。
- 即使並非必要，JWT 仍可涵蓋車輛和行程作業，這有助於簡化權杖簽署實作程序。

deliveryvehicleid

呼叫每個送貨車輛的 API 時使用。
taskid

呼叫每個工作 API 時使用。
taskids

在呼叫 BatchCreateTasksAPI 時使用。這項聲明必須採用陣列形式，且陣列應包含完成要求所需的所有工作 ID。請勿加入 delivervehicleid、trackingid 或 taskid 聲明。
trackingid

呼叫 GetTaskTrackingInfoAPI 時使用。聲明必須與要求中的追蹤 ID 相符。請勿加入 delivervehicleid、taskid 或 taskids 聲明。