全部產品
Search

搜尋本產品

    ID Verification：服務端API介面

    文件中心

    ID Verification：服務端API介面

    更新時間：Dec 02, 2025

    本文介紹FACE_GUARD的服務端構建方法。

    介面說明

    • 介面名：FaceGuardRisk

    • 要求方法：POST和GET

    • 傳輸協議：HTTPS

    • 重要

      FACE_GUARD按照查詢成功計量，建議您同一個 Device Token 查詢成功後不要再重複查詢，避免重複計量。

    • QPS限量：API獨享QPS限量，詳情請參見ID Verification服務端API QPS限量說明。

    • 全域接入地址：

      說明

      • 內網指的是阿里雲同地區產品之間的內部通訊網路，如果您的商務服務器部署在阿里雲的對應地區，可以通過內網網域名稱訪問 ID Verification 服務，以獲得更安全、穩定的網路通訊品質。

      • 裝置助手為了滿足不同地區資料收集合規要求，提供了不同的資料上報網站，不同的網站之間資料隔離。

        用戶端通過設定CustomUrl和CustomHost指定不同的上報網站，服務端需要基於用戶端上報的網站，訪問指定網域名稱進行查詢才能擷取詳情資訊。

      中國香港

      • 公網：cloudauth-intl.cn-hongkong.aliyuncs.com

      • 內網：cloudauth-intl-vpc.cn-hongkong.aliyuncs.com

    線上調試和整合

    說明

    在調試和整合前，請確保您已完整閱讀使用OpenAPI調試和整合服務端API文檔，充分瞭解API介面在OpenAPI平台的調用方式和SDK及其代碼的擷取方式。

    您可以在OpenAPI Explorer中直接運行本介面進行調試，並產生本介面的SDK程式碼範例。

    請求參數

    參數

    類型

    是否必選

    描述

    樣本值

    ProductCode

    String

    是

    產品code：FACE_GUARD（固定值）。

    FACE_GUARD

    MerchantBizId

    String

    是

    您自訂的業務唯一標識，用於後續定位排查問題使用，支援長度為32位的字母和數位組合，請確保唯一。

    e0c34a77f5ac40a5aa5e6ed20c35****

    DeviceToken

    String

    是

    通過用戶端SDK擷取的deviceToken。

    Tk9SSUQuMS*****************ZDNmNWY5NzQxOW1o

    BizId

    String

    否

    本次業務認證的唯一ID，主要配合FACE_GUARD用於查詢時校正。

    1000******0001

    返回參數

    名稱

    類型

    描述

    樣本值

    RequestId

    String

    請求ID。

    130A2C10-B9EE-4D84-88E3-5384FF03****

    Code

    String

    返回碼，200指介面響應成功。詳細認證結果判斷，請點擊下方返回Code摺疊框查看。

    Success

    Message

    String

    返回Code的詳細描述。

    success

    Result.TransactionId

    String

    整個認證流程的唯一標識。

    e0c34a77f5ac40a5aa5e6ed20c35****

    Result.RiskTags

    String

    裝置風險標籤。多個裝置風險標籤以半形逗號,分隔。如需瞭解更多裝置風險標籤及其含義，請點擊下方風險標籤（RiskTags）摺疊框查看。

    ROOT,VPN,HOOK

    Result.RiskExtends

    String

    拓展資訊，預設為空白。

    {
  "code": 200
  "message":"success"
  "umid":"07d3295d3d597b425d102a7f********",
  "sip":"198.51.100.1",
  "durationMs" : 4968931
  "queryCount":1,
  "querySessionCount":1,
  "queryUmidCount":1
  "platform":"Android
}

    Result.GuardRiskScore

    Double

    裝置助手演算法預測的裝置風險可能性，分數越高代表裝置風險越高。

    分值取值：0~100。

    99

    點擊查看：返回Code

    HTTP狀態代碼

    Code

    Message描述

    200

    Success

    請求成功。

    400

    MissingParameter

    參數不可為空。

    InvalidParameter

    非法參數。

    401

    Forbidden.ExceptionRepeatedInvoke

    異常重複調用次數超限。

    403

    Forbidden.RAMUserAccessDenied

    需要給RAM使用者授予AliyunAntCloudAuthFullAccess操作許可權。更多資訊，請參見授權RAM使用者訪問服務。

    Forbidden.AccountAccessDenied

    確保您開通了ID verifycation，並且保證賬戶未欠費。

    Throttling.Api

    API限流攔截。

    429

    SuspiciousActivity

    安全性原則限制，請稍後重試。

    500

    InternalError

    系統內部錯誤，請反饋工程師排查。

    503

    ServiceUnavailable

    服務不可用，請反饋工程師排查。

    點擊查看：風險標籤（RiskTags）

    風險類別

    風險標籤

    描述

    裝置風險類（Native SDK）

    ROOT

    裝置疑似ROOT、越獄。

    HOOK

    裝置疑似HOOK。

    VPN

    裝置疑似VPN。

    Emulator

    裝置疑似模擬器。

    SystemVirtual

    裝置系統多開。

    重要

    僅支援安卓

    ThirdVirtual

    裝置三方多開。

    重要

    僅支援安卓

    AdbModel

    裝置開啟開發人員模式。

    重要

    僅支援安卓

    DebugModel

    偵錯模式

    NoSimCard

    裝置未插卡。

    VirtualVideo

    安裝虛擬視頻工具。

    UsingVirtualVideo

    使用虛擬視頻工具。

    MirroredScreen

    螢幕錄屏截屏。

    重要

    僅支援iOS

    RiskROM

    高危定製ROM。

    重要

    僅支援安卓

    UnusualROM

    非常規ROM。

    重要

    僅支援安卓

    AutoOperation

    自動化操作。

    BlackTool

    安裝高危工具。

    CloudPhone

    雲手機。

    重要

    僅支援安卓

    BootUnLock

    裝置boot解鎖

    重要

    僅支援安卓

    BootCountLittle

    裝置啟動次數較少

    重要

    僅支援安卓

    ChargeScreenBright

    手機充電螢幕長亮。

    重要

    僅支援安卓

    ChargeScreenNoSecure

    手機充電無鎖屏密碼。

    重要

    僅支援安卓

    ChargeWithUsb

    手機USB充電中。

    重要

    僅支援安卓

    FakeDevice

    改機，包括但不限於裝置機型、裝置特徵篡改。

    AbnormalPort

    裝置連接埠異常。

    重要

    僅支援安卓

    裝置風險類（Web SDK）

    VirtualBrowser

    疑似虛擬瀏覽器。

    VirtualCamera

    疑似安裝虛擬網路攝影機。

    UsingVirtualCamera

    疑似使用虛擬網路攝影機。

    AutoOperation

    疑似自動化工具。

    BrowserTampered

    疑似瀏覽器參數被篡改。

    Debugger

    疑似頁面JS被調試。

    CloudPhone

    疑似雲手機環境

    WebCrawler

    疑似惡意爬蟲/協議刷調用

    CookieDisabled

    cookie被禁用。

    Incognito

    瀏覽器處於隱藏模式。

    MediaHook

    瀏覽器視頻流API被Hook

    NoRefer

    人臉認證頁面無 referrer 來源。

    說明

    需配合ID Verification，獨立整合裝置助手無此標籤。

    UnmatchOsUrl

    認證頁面 URL 和裝置不匹配。

    說明

    需配合ID Verification，獨立整合裝置助手無此標籤。

    DeviceToken風險類

    TokenIsNull

    deviceToken為空白。

    TokenTampered

    deviceToken篡改。

    TokenInvalid

    deviceToken無效。

    TokenExpired

    deviceToken到期（7天有效）。

    通用類

    BizIdNotMatch

    業務傳入的 bizId 和 token 中的 bizId 綁定關係不匹配，常見於 token 替換或者類比等攻擊手段。

    說明

    若出現比例較高，建議優先排查用戶端整合鏈路調用getDevieToken 中的 bizId 與裝置助手查詢介面傳入bizId配置一致性。

    DeviceBadNet

    弱網環境（裝置助手初始化未成功）。

    說明

    若出現比例較高，建議優先排查用戶端整合鏈路。

    通常是因為用戶端初始化和getDeviceToken介面未按照官網標準時序圖接入導致，建議參考官網文檔調整擷取token時機。

    ReportingGap

    裝置助手採集資料上報缺失。

    說明

    若出現比例較高，建議優先排查用戶端整合鏈路。

    通常是因為用戶端初始化和getDeviceToken介面未按照官網標準時序圖接入導致，建議參考官網文檔調整擷取token時機。

    業務情境類

    HighRiskEnv

    黑灰產高危環境，綜合判斷為黑灰產高危環境。

    說明

    該標籤為綜合性質標籤，基於線上積累的攻防經驗沉澱，多維組合條件判斷結果。

    MiddleRiskEnv

    黑灰產中危環境，綜合判斷為黑灰產中危環境。

    說明

    該標籤為綜合性質標籤，基於線上積累的攻防經驗沉澱，多維組合條件判斷結果。

    PermittedDevice

    白名單裝置。

    說明

    該裝置被設定為白名單，預設GuardRiskScore為0分。

    BlackListedDevice

    黑名單裝置。

    說明

    該裝置被識別存在重複攻擊行為，預設GuardRiskScore為100分。

    其他

    NoRisk

    裝置風險較低。

    當系統未檢測出上述風險時返回NoRisk標籤。

    NoTag

    無資料返回。

    當因為ID Verification系統異常無法擷取風險標籤時，系統自動返回NoTag標籤。

    點擊查看：Result.RiskExtends 返回欄位詳細說明

    欄位

    含義

    詳細說明

    code

    token狀態code

    • 200：token正常情況

    • 401：token內資料異常

    • 404：token內資料格式異常

    • 407：token到期（7天內有效）

    • 408：token或上報資料篡改

    • 500：token未知異常

    message

    token錯誤資訊

    token相關錯誤資訊，code非200時有值。

    umid

    裝置唯一ID

    07d3295d3d597b425d102a7f********

    platform

    裝置所處的平台

    • Android

    • iOS

    • Harmony

    • Web

    sip

    用戶端IP

    198.51.100.1

    durationMs

    查詢時和端上初始化之間的時間差，單位毫秒。

    4968931

    queryCount

    該token來當日查詢的次數

    1

    querySessionCount

    該token所處會話當日來查詢的次數

    2

    queryUmidCount

    該裝置當日來查詢的次數

    2