JSON Web Token

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

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

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

重要詳細資料

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

JWT 元素

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

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

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。

如要指定工作 ID，授權範圍必須是下列其中一種形式的陣列：

"taskids": ["task_id_one","task_id_two"]

或

"taskids": ["*"]

Fleet Engine JWT 聲明

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 聲明。

後續步驟