logo

额外区块类型 (EBT) - 全新的布局构建器体验❗

额外区块类型 (EBT) - 样式化、可定制的区块类型：幻灯片、标签页、卡片、手风琴等更多类型。内置背景、DOM Box、JavaScript 插件的设置。立即体验布局构建的未来。

演示 EBT 模块 下载 EBT 模块

❗额外段落类型 (EPT) - 全新的 Paragraphs 体验

额外段落类型 (EPT) - 类似的基于 Paragraph 的模块集合。

演示 EPT 模块 滚动

滚动
  1. 首页
  2. JSON Drop API 文档
  3. 认证、安全与性能

API 密钥认证

03/09/2025, by Ivan
Download JSON Drop API

JSON Drop API Documentation

API 密钥认证是保护 Drupal REST API 最简单的方法之一。一旦你为所有用户生成了 API 密钥，就可以使用这些密钥来保护对 Drupal REST API 的访问。

你可以在每个 API 请求的 Authorization 头中发送用户的 Drupal 用户名和 API 密钥来实现。Drupal API Authentication 模块将会根据用户名和对应的 API 密钥来验证请求。该模块兼容 Drupal 7、Drupal 8、Drupal 9、Drupal 10 和 Drupal 11。

 下载 

设置视频：

Drupal REST API Key Authentication Youtube Video

前提条件：下载与安装：

  • 下载并安装 Drupal REST & JSON API Authentication 模块。
  • REST UI：该模块为你提供了一个配置 REST 模块的用户界面。
  • 在你的 Drupal 站点的扩展（/admin/modules）部分启用以下 Web Services 模块：
    • REST UI
    • RESTful Web Services
    • Serialization

    Drupal Rest api

在 Drupal 中设置基于 API Key 的认证步骤：

  • 为了更好地理解，我们将以在 Drupal 中为 Create User API 添加基于 API Key 的认证为例。
  • 请注意，Drupal 的 /entity/user API 用于在 Drupal 中创建用户。

启用 API 并分配如下方法与操作：

  • 第一步是启用 API，并指定该 API 允许的方法和操作。这可以通过 REST UI 模块完成，或者直接修改配置。
  • 要使用 REST UI 模块启用 API，请点击 REST UI 模块的 配置 按钮（如下所示）。

    api key

  • 在我们的示例中，我们需要启用 /entity/user API。使用前面的启用选项来启用此 API。

    api key

  • 现在，因为我们的目标是创建一个 Drupal 用户，请选择以下配置：
    • 方法：POST
    • 格式：json
    • 认证提供者：rest_api_authentication
  • 选择 rest_api_authentication 将允许 miniOrange REST API Authentication 模块来验证你的 /entity/user API。点击 保存配置 按钮继续。

    drupal select

在 Drupal 中创建 API Key 用户字段：

注意：如果你使用的是该模块的免费版本，可以跳过此步骤。

在此步骤中，我们将设置如何使用 API 密钥来验证 API 调用。为此，我们需要先创建一个用于存储 API 密钥的用户属性字段。

  • 导航到 Drupal 的管理字段 (/admin/config/people/accounts/fields) 标签页。
  • 要添加字段，请点击 添加字段 按钮。

    manage fields

  • 在 添加新字段 下拉菜单中，选择 文本（纯文本） 选项，并在标签文本框中输入 API Key。然后点击 保存并继续 按钮以保存设置。
  • 请确保用户属性的机器名为 field_api_key。

    Add field

  • 然后继续点击 保存字段设置，再点击 保存设置 按钮以完成字段创建。

    Save field

    Drupal API key settings

  • 你现在可以在用户资料中看到一个额外的 API Key 文本字段。

设置基于 API Key 的认证：

  • 在此步骤中，我们将生成一个 API Key。请导航到 REST API Authentication 模块的 API 认证标签页。(/admin/config/people/rest_api_authentication/auth_settings)
  • 勾选 启用认证 复选框并点击 保存设置。
  • 要启用基于 API Key 的认证，选择 API Key 单选按钮。
  • 在同一页面上，你可以为某个用户生成 API Key，或者一次性为所有用户生成。
  • 现在我们只为一个用户生成 API Key。
  • 在 输入用户名 文本框中输入你要生成 API Key 的用户名，然后点击 为该用户生成 API key 按钮。
  • 你现在可以在用户资料的 API Key 字段中查看生成的 API Key。

    REST API create key

  • 请保存 API Key，因为稍后在认证 API 时需要用到。

授予 Drupal 角色创建用户的权限：

  • 如果需要，你还可以授予非管理员的 Drupal 角色在 Drupal 中创建用户的权限。你可以通过在 Drupal 站点的权限部分（/admin/people/permissions）为角色分配 管理用户 权限来实现。

    REST API

就是这样！！！

  • 现在让我们尝试通过 API 调用使用 API Key 来在 Drupal 中创建一个用户。

示例：

  • 要在 Drupal 中创建用户，你需要发送一个 POST 请求，并附带 miniOrange REST API Authentication 模块颁发的用户名和 API Key。用户名和 API Key 的值必须是 base64 编码格式。你可以参考以下格式来调用。

    请求： POST <your_drupal_base_url>/entity/user?_format=json
    头部：Authorization: Basic base64encoded <username:api_key>
            Accept: application/json
            Content-Type: application/json

    请求体：

    {
        "name": [
            {"value": "<username>"}
        ],
        "mail": [
            {"value": "<email>"}
        ],
        "pass":[
            {"value": "<password>"}
        ],
        "status":[
            {"value": "1"}
        ]
    }

    CURL 请求格式 -

    curl --location --request POST ‘<your_drupal_base_url>/entity/user?_format=json' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic base64encoded<username:API key>’ \
    --data-raw '

    {
        "name": [
            {"value": "Username"}
        ],
        "mail": [
            {"value": "email"}
        ],
        "pass":[
            {"value": "Password"}
        ],
        "status":[
            {"value": "1"}
        ]
    }'

  • 你还可以参考下方添加的 Postman 请求示例图片：

    postman

  • 成功的响应会返回你所创建的用户信息。（请参考下图）

    Postman response

  • 如果你在响应中收到错误，可以参考下表中的错误描述和可能的解决方法。

错误响应：

错误 描述
MISSING_AUTHORIZATION_HEADER

当你没有在 API 请求中发送 Authorization 头，或者该头因某些原因被服务器移除时，你将会收到此错误。

示例：
{
  "status": "error",
  "error": "MISSING_AUTHORIZATION_HEADER",
  "error_description": "Authorization header not received."
}
INVALID_AUTHORIZATION_HEADER_TOKEN_TYPE 当你发送 Authorization 头但格式不正确时，将会收到此错误。
示例：
{
  "status": "error",
  "error": "INVALID_AUTHORIZATION_HEADER_TOKEN_TYPE",
  "error_description": "Authorization header must be the type of Basic Authentication."
}
USER_DOES_NOT_EXIST

当模块未找到与请求中发送的用户名对应的账户时，你将会收到此错误。

示例：
{
  "status": "error",
  "error": "USER_DOES_NOT_EXIST",
  "error_description": "The user does not exist."
}
INVALID_API_KEY

当 API 调用中发送的 API Key 不匹配时，你将会收到此错误。

示例：
{
  "status": "error",
  "error": "INVALID_API_KEY",
  "error_description": "The API Key sent in the Request seems to be invalid or incorrect using invalid API Key."
}
USER_NAME_MISSING

当模块无法在 API 调用中找到用户名时，你将会收到此错误。

示例：
{
  "status": "error",
  "error": "USER_NAME_MISSING",
  "error_description": "The username is missing from the request"
}
INVALID_AUTHORIZATION_HEADER

当模块无法正确解码请求头，或在头部未找到用户名和 API Key 时，你将会收到此错误。

示例：
{
  "status": "error",
  "error": "INVALID_AUTHORIZATION_HEADER",
  "error_description": "The authorization header seems to be invalid"
}

文章来源 Drupal 文档。