指令碼開發 / API 認證

對於「函式 API」所生成的 HTTP API，可以額外新增介面認證。

目前支援的介面認證如下：

認證型別	說明
固定欄位	驗證請求的 Header, Query 或 Body 中必須包含具有特定值的欄位
HTTP Basic	標準 HTTP Basic 認證（在瀏覽器中訪問可彈出登入框）
HTTP Digest	標準 HTTP Digest 認證（在瀏覽器中訪問可彈出登入框）
認證函式	指定自行編寫的函式作為認證函式

使用者可以在「管理 / API 認證」新增認證配置，隨後在「函式 API 配置」中指定所新增的認證配置。

如對安全性有較高要求，請務必使用 HTTPS 方式訪問介面

1. 固定欄位認證

固定欄位認證是最簡單的認證方式，即客戶端與 DataFlux Func 約定在請求的某處（Header、Query 或 Body）包含一個特定的欄位和欄位值，在每次呼叫時附帶此內容以完成認證。

假設約定每次請求中，請求頭必須包含 x-auth-token="my-auth-token"，那麼按照以下方式呼叫即可完成認證：

Text Only
GET /api/v1/al/func-api-xxxxx
x-auth-token: my-auth-token

配置多個固定欄位認證時，有一個匹配即認為透過認證

對於 Query 和 Body 中用於認證的欄位，認證通過後系統會自動將其刪除，不會傳遞到函式

2. HTTP Basic / HTTP Digest

瀏覽器直接支援的認證方式。

使用此方式認證的介面，在瀏覽器位址列中直接訪問時，瀏覽器會彈出使用者名稱/密碼框供使用者填寫。

如需要使用程式設計方式訪問，請參考如下程式碼：

Python
import requests
from requests.auth import HTTPBasicAuth, HTTPDigestAuth

# HTTP Basic 認證
resp = requests.get(url_1, auth=HTTPBasicAuth('user', 'password'))

# HTTP Digest 認證
resp = requests.get(url_2, auth=HTTPDigestAuth('user', 'password'))

3. 認證函式

如果介面認證方式複雜或特殊（如需要對接業務系統等），可以選擇自行編寫函式方式認證。

用於認證的函式不需要引數，返回 True 表示認證成功，返回其他內容或丟擲錯誤表示失敗。

在認證函式中，可以使用內建變數 _DFF_HTTP_REQUEST 獲取請求相關資訊：指令碼開發 / 內建變數 / _DFF_HTTP_REQUEST

示例
@DFF.API('認證函式')
def my_auth_func():
    return _DFF_HTTP_REQUEST['headers']['x-auth-token'] == 'my-auth-token'

需要注意的是，在認證失敗時，根據返回內容不同，介面的返回格式也會有所不同：

返回 False返回字串返回 JSON丟擲錯誤

示例
@DFF.API('認證函式')
def my_auth_func():
    return False

認證失敗，直接返回 False 時，介面響應體中不會包含任何具體錯誤資訊：

介面響應體
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail" : false,
  "status" : 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}

示例
@DFF.API('認證函式')
def my_auth_func():
    return 'Bad User!'

認證失敗，返回字串時，此字串會作為 detail 欄位返回：

介面響應體
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail" : "Bad User!",
  "status" : 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}

示例
@DFF.API('認證函式')
def my_auth_func():
    return { 'error': 'Bad User!' }

認證失敗，返回 JSON 時，此 JSON 會作為 detail 欄位返回：

介面響應體
{
  "ok"     : false,
  "error"  : 401.99,
  "reason" : "EAPIAuth",
  "message": "Func Auth failed",
  "detail": {
    "error": "Bad User!"
  },
  "status": 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}

示例
@DFF.API('認證函式')
def my_auth_func():
    raise Exception('Bad User!')

當認證函式丟擲錯誤時，由於 Func 框架層面無法感知此 Exception 屬於業務邏輯還是程式碼本身報錯，因此會返回通用的錯誤資訊作為 detail 欄位：

介面響應體
{
  "ok": false,
  "error": 401.99,
  "reason": "EAPIAuth",
  "message": "Func Auth failed",
  "detail": {
    "name"               : "Func.Runner",
    "id"                 : "task-RWLH3EuCRfYl",
    "triggerTime"        : 1755170213.119,
    "startTime"          : 1755170213.122,
    "endTime"            : 1755170213.13,
    "status"             : "failure",
    "exceptionType"      : "UserScriptException",
    "exception"          : "In User Script: Exception('Bad User!')",
    "exceptionFrom"      : "userScript",
    "originExceptionType": "Exception",
    "originException"    : "Exception('Bad User!')"
  },
  "status": 401,
  "reqDump": {
    "method": "GET",
    "url"   : "http://localdev:8089/api/v1/func-api/xxxxx/s"
  },
  "traceId"   : "TRACE-XXXXX",
  "clientTime": null,
  "reqTime"   : "2025-08-14T11:03:45.238Z",
  "respTime"  : "2025-08-14T11:03:45.406Z",
  "reqCost"   : 168
}