如何在 Drupal 11 中使用 Webform REST 模块：实用指南
在不断发展的网页开发领域中，Drupal 11 脱颖而出，成为构建动态网站和应用程序最强大、最灵活的平台之一。它的模块化架构使开发人员能够定制和扩展核心功能，以满足各种项目需求。
其中一个扩展就是 Webform REST 模块，它是一个强大的工具，通过 RESTful API 实现 Drupal 与外部应用之间的无缝集成。本指南提供了一个在 Drupal 11 中使用 Webform REST 模块的实用入门，带领你完成其安装与配置，并演示如何高效地与其交互。
你将学到什么
本文涵盖以下主题：
-
Webform REST 模块概述
-
所需模块和依赖项
-
安装 Webform REST 和 REST UI
-
配置 Webform REST 模块
-
处理 CORS
-
发送 API 请求
-
理解请求和响应载荷
模块概述：Webform REST
Webform REST 模块通过暴露基于表单的功能为 RESTful 端点扩展了 Drupal 的 Webform 能力。通过它，你可以执行创建、查看、更新和删除 Web 表单等操作，还可以通过 HTTP 请求提交和获取表单数据。
该模块在将 Drupal 与以下外部平台集成时尤其有用：
-
CRM 系统
-
电子邮件营销工具
-
移动应用
-
第三方服务
通过启用这些集成，你可以简化工作流并集中数据收集，大幅提升应用的整体效率。
前提条件
要开始使用 Webform REST，请确保已安装以下模块：
-
Webform – 用于构建和管理 Web 表单
-
REST UI – 用于配置 RESTful 端点和权限
-
Webform REST – 提供 API 功能的主要模块
安装 Webform REST 和依赖
在本指南中，我们使用 Docker 和 Lando 管理本地开发环境，并使用 Composer 管理依赖。
要安装 Webform REST 模块，请运行以下命令：
$ lando composer require 'drupal/webform_rest:^4.0'
启用模块：
$ lando drush en webform_rest
此外，还需要启用 REST UI 模块，它允许你通过管理界面配置 REST 端点：
$ lando drush en restui
或者，你也可以通过管理界面启用这些模块：
/admin/modules
配置 Webform REST 模块
启用所需模块后，前往 REST 配置页面：
路径： /admin/config/services/rest
启用以下 REST 资源：
-
Webform Submission
-
Webform Elements
-
Webform Submit
这些资源为通过 REST 与表单及其数据交互提供了基本端点。
必须至少选择一种认证方式，在我们的示例中是 “cookie”。
要允许未认证用户通过 Web 表单提交请求，必须为 Anonymous 用户角色授予相应的权限。具体来说，允许他们对 Webform Submit REST 资源执行 POST 请求。
此权限可在以下位置配置：
/admin/people/permissions
在 “RESTful Web Services” 部分，为 Anonymous 用户勾选 “Access POST on Webform Submit resource”。这确保了外部用户或无认证系统可以通过 Webform REST API 成功向你的 Drupal 网站提交数据。
关于 CORS
如果你打算从与应用安装不同的域发起请求，可能会遇到如下 CORS 问题：
理解并配置 Drupal 11 中的 CORS
CORS（跨域资源共享）是由网页浏览器实现的一项关键安全机制，用于控制不同来源之间的资源访问，其中 来源 定义为域名、协议和端口的组合。
简单来说，CORS 允许服务器指定哪些外部域可以通过基于浏览器的请求访问特定资源。如果没有正确配置的 CORS 策略，浏览器会回退到 同源策略，阻止来自非当前页面来源的资源访问。
在 Drupal 11 中配置 CORS
Drupal 11 通过 services.yml 文件中的 cors.config 部分管理 CORS 设置。默认情况下该配置是禁用的，这意味着跨域请求会被阻止，除非明确允许。
要为外部客户端（如 JavaScript 前端或移动应用）启用 CORS，需要修改 services.yml 文件中的配置。以下是用于开发或测试的宽松配置示例：
cors.config:
enabled: true
allowedHeaders: ['x-csrf-token','authorization','content-type','accept','origin','x-requested-with', 'access-control-allow-origin','x-allowed-header','*']
allowedMethods: ['*']
allowedOrigins: ['*']
exposedHeaders: false
maxAge: false
supportsCredentials: true
在本地开发中配置 services.local.yml
在大多数 Drupal 本地开发环境中，你会有一个名为 services.local.yml 的文件。该文件专门用于覆盖主 services.yml 中的配置。因此，如果 services.local.yml 中存在冲突或不完整的设置，你对 services.yml 的更改可能会被忽略。
为确保 CORS 配置 正确应用，请在 services.local.yml 中复制或修改相应设置。
配置后清理缓存
更新 YAML 配置文件后，清理 Drupal 缓存以应用更改：
$ lando drush cr
注意 YAML 缩进
YAML 缩进问题很常见，必须小心。即使是一个错误的空格或制表符，也可能导致设置被忽略，造成大量无谓的调试。如果更改没有生效，首先检查缩进。
使用 Webform REST 模块
配置完成后，你可以开始通过 REST 提交表单。此过程包括向 Webform REST 端点发送 POST 请求，并附上必要的头信息和载荷。
端点
POST /webform_rest/submit
必需的请求头
Content-Type: application/json
示例：使用 Axios 提交表单
以下是使用 JavaScript 中 Axios 提交表单数据的示例：
const response = await axios.post('http://yoursite.lndo.site/webform_rest/submit', {
"webform_id": "some_rest_form",
"name": "Ivan Abramenko",
"email": "levmyshkin89@gmail.com",
}, {
headers: {
"Content-Type": 'application/json',
},
});
此示例展示了如何使用 Axios 发送 POST 请求，但你也可以使用其他 HTTP 库或框架来发送请求。
请求载荷主要由目标表单的机器名 webform_id 及其注册字段组成。
{
"webform_id": "some_rest_form",
"name": "Ivan Abramenko",
"email": "levmyshkin89@gmail.com"
}
成功提交后的响应载荷包括以下字段：
sid：已记录提交的唯一标识符confirmation_url：提交确认 URLconfirmation_message：确认消息confirmation_title：确认消息的标题
{
"sid": "ae8c3bd4-91a2-5c17-a264-59c86157457b",
"confirmation_type": "inline",
"confirmation_url": "",
"confirmation_message": "Just a confirmation message",
"confirmation_title": "A confirmation title"
}
此外，我们还可以获取由 Webform 本身生成的验证消息。例如，如果未提交必填字段，会收到以下响应：
{
"message": "Submitted Data contains validation errors.",
"error": {
"email": "The email field is mandatory."
}
}
处理 API 响应
通过 API 返回的响应数据，你可以在程序中向用户提供反馈，例如 成功确认、验证错误 或 提交失败。合理处理这些响应能增强用户体验，确保交互过程的清晰性。
无论你是将表单与前端框架还是移动应用集成，有效管理 API 响应都是提供流畅直观体验的关键。
总结
Webform REST 模块为 Drupal 11 提供了一种强大且灵活的解决方案，用于通过 RESTful API 与 Web 表单交互。通过允许外部应用提交和操作表单数据，它大大扩展了 Drupal 的集成能力——非常适合依赖解耦或无头架构的现代 Web 体系。
在本文中，我们探讨了：
-
Webform REST 模块简介
-
逐步安装与配置
-
如何通过 API 提交数据的实用示例
虽然本指南专注于 表单提交，但 Webform REST 模块还支持其他未涉及的操作，包括：
-
PATCH 请求，用于更新现有提交
-
GET 请求，用于获取提交数据或列出表单字段
-
更多关于认证与访问控制的自定义
这些高级用例将在后续教程中探讨。