路线{ #route }¶

route.remote_servers_allowed "是一个以逗号分隔的 URL 模式列表，默认设置为 "https://*"。DHIS2 管理员应将默认值改为限制性更强的 URL，以防止服务器端请求伪造（SSRF）攻击。虽然出于安全原因不建议这样做，但可以在 `route.remote_servers_allowed` 中添加通配符条目，这样就可以避免枚举每个允许的远程服务器：

属性
route.remote_servers_allowed = https://*.server1.com/

将上述请求发送至 `/api/routes` API 端点后，即可从 DHIS2 运行路由。您可以使用返回的 ID 或分配给它的代码运行路由，如下图所示：

如果希望 DHIS2 将请求 _POST_ 发送到路由目标，请在调用 `run` 端点时使用 _POST_ HTTP 方法，而不是 `GET` HTTP 方法：

### 使用验证运行路由{ #running-a-route-with-authentication } 

运行路由时支持多种身份验证模式。这些验证模式会在 DHIS2 发送的路由请求中添加标头或查询参数。在使用验证模式创建路由时，DHIS2 会对敏感的标头或查询参数进行加密。这意味着无法从数据库或 Web API 读取明文机密。以下是支持的验证模式：

* http-basic`：在路由请求中添加一个 _Authorization_ 标头，用于 HTTP 基本访问身份验证。下面是创建配置了 `http-basic` 身份验证的路由的示例：

  ```json
  {
    "name": "Postman Echo",
    "code": "postman-get",
    "disabled": false,
    "url": "https://postman-echo.com/get",
    "auth": {
      "type": "http-basic",
      "username": "admin",
      "password": "admin"
    }
  }
  ```

* api-token`：为[Personal Access Token (PAT) authentication]（个人访问令牌（PAT）身份验证）添加一个 _Authorization_ 标头(https://docs.dhis2.org/en/use/user-guides/dhis-core-version-master/working-with-your-account/personal-access-tokens.html) 。值得注意的是，PAT 身份验证是 DHIS2 特有的，因此如果路由的目标 URL 不是 DHIS2 实例，你可能需要考虑使用更通用的 `api-headers` 身份验证模式（将在下文介绍）。下面是一个创建路由的示例，路由配置了 "api-token "身份验证：

  ```json
  {
    "name": "Postman Echo",
    "code": "postman-get",
    "disabled": false,
    "url": "https://postman-echo.com/get",
    "headers": {
      "a": "1",
      "b": "2",
      "c": "3"
    },
    "auth": {
      "type": "api-token",
      "token": "74478F79-7B85-424A-9C93-8A6F924AA9F9"
    }
  }
  ``` 
  请注意，该请求将路由配置为静态标头，以便 DHIS2 发送的请求中包含这些标头。请注意，DHIS2 不会将这些静态标头加密存储。 

* api-headers`：为 API 身份验证添加用户定义的标头。下面是创建配置了 `api-headers` 身份验证的路由的示例：

  ```json
  {
    "name": "Postman Echo",
    "code": "postman-get",
    "disabled": false,
    "url": "https://postman-echo.com/get",
    "auth": {
      "type": "api-headers",
      "headers": {
        "X-API-KEY": "aXJgm4Kwv1xk9UfFRYIIR8b6mEV1cQz3lcxMQlaQz9lwI35j4ZIUK5T2O2aQDfIY"
      }
    }
  }
  ```

* api-query-params`：为 API 身份验证添加用户定义的查询参数。下面是创建配置了 `api-query-params` 身份验证的路由的示例：

  ```json
  {
    "name": "Postman Echo",
    "code": "postman-get",
    "disabled": false,
    "url": "https://postman-echo.com/get",
    "auth": {
      "type": "api-query-params",
      "queryParams": {
        "token": "aXJgm4Kwv1xk9UfFRYIIR8b6mEV1cQz3lcxMQlaQz9lwI35j4ZIUK5T2O2aQDfIY"
      }
    }
  }
  ```

### 使用身份验证和自定义权限运行路由{ #running-a-route-with-authentication-and-custom-authority } 

在下面的示例中，我们使用 "http-basic "身份验证配置路由，并为其分配自定义权限：

``json
{
  "name"："Postman Echo"、
  "代码"："postman-post"、
  "disabled": false、
  "url"："https://postman-echo.com/post"、
  "auth"：{
    "类型"："http-basic"、
    "用户名"："admin"、
    密码"admin
  },
  "权限"：["my_custom_app"]
}

允许的最小响应超时时间为 1 秒，最大超时时间为 60 秒。应谨慎使用 `responseTimeoutSeconds` 设置，因为并发的、长时间运行的路由可能会降低 DHIS2 的整体性能。 

>重要： 从 DHIS2 v40.10 和 v41.6 开始，可以自定义响应超时。早期版本的 DHIS2 响应超时为 10 秒，以下版本除外：
>* 40.8 ≤ v< 40.10
>* 41.4 ≤ v< 41.6
>
>这些版本的响应超时为 30 秒。

### 通配符路由{ #wildcard-routes } 

可以创建支持子路径请求的 "通配符路由"，然后将其传递给上游服务。为此，路由 URL 必须以 `/**` 结尾。然后，可以在 `/run`后追加子路径来指定子路径。

``json
{
  "name"："Postman Wildcard"、
  "code"："postman-wildcard"、
  "disabled": false、
  "url"："https://postman-echo.com/**"
}

GET /api/routes/{id}/run/get
GET /api/routes/postman-wildcard/run/get
POST /api/routes/{id}/run/post
POST /api/routes/postman-wildcard/run/post