--- url: 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/reference/api-endpoints' title: 'API 端点 | DXPR' author: name: Jurriaan url: 'https://dxpr.com/users/jurriaan' date: '2026-10-24T08:21:06+00:00' updated: '2026-10-24T09:09:48+00:00' copyright: 'Copyright DXPR. All rights reserved.' type: article summary: |- 本页列出 DXPR Builder 在以下位置注册的每个路由 dxpr_builder.routing.yml，含控制器实现的 HTTP 方法、访问要求、请求参数和响应结构。编辑器的 JavaScript 是 AJAX 端点的预期客户端；本页没有任何稳定的公开 API，参数名称可能在版本之间变化。 访问要求 路由使用三种要求。一个路由可以组合它们。 tags: - 'Configuratie en API' image: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg' published: true og: site_name: DXPR updated_time: '2026-10-24T09:09:48+0000' 'image:alt': 'DXPR, powered by Drupal: AI-powered Drupal for marketers.' schema: '@context': 'https://schema.org' '@graph': - mainEntity: { } - '@type': TechArticle headline: 'API 端点' description: |- 本页列出 DXPR Builder 在以下位置注册的每个路由 dxpr_builder.routing.yml，含控制器实现的 HTTP 方法、访问要求、请求参数和响应结构。编辑器的 JavaScript 是 AJAX 端点的预期客户端；本页没有任何稳定的公开 API，参数名称可能在版本之间变化。 访问要求 路由使用三种要求。一个路由可以组合它们。 image: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/images/dxpr-share-card.jpg' width: '1200' height: '630' datePublished: '2026-10-24T08:21:06+0000' dateModified: '2026-10-24T09:09:48+0000' author: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR url: 'https://dxpr.com/' logo: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg' width: '1348' height: '501' publisher: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR url: 'https://dxpr.com/' logo: '@type': ImageObject url: 'https://dxpr.com/themes/custom/dxpr_com/dxpr-logo-dark.svg' width: '1348' height: '501' mainEntityOfPage: 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/reference/api-endpoints' articleSection: 'Configuratie en API' - '@type': WebPage '@id': 'https://dxpr.com/zh-hans/hc/documentation/learn-dxpr-builder/reference/api-endpoints' description: |- 本页列出 DXPR Builder 在以下位置注册的每个路由 dxpr_builder.routing.yml，含控制器实现的 HTTP 方法、访问要求、请求参数和响应结构。编辑器的 JavaScript 是 AJAX 端点的预期客户端；本页没有任何稳定的公开 API，参数名称可能在版本之间变化。 访问要求 路由使用三种要求。一个路由可以组合它们。 breadcrumb: '@type': BreadcrumbList itemListElement: - '@type': ListItem position: 1 name: 首页 item: 'https://dxpr.com/zh-hans' publisher: '@type': Organization '@id': 'https://dxpr.com/#organization' name: DXPR inLanguage: zh-hans --- [Help Center](/zh-hans/node/75)/[Documentation](/zh-hans/hc/documentation) /[Learn DXPR Builder](/hc/documentation/learn-dxpr-builder) /[Reference](/hc/documentation/learn-dxpr-builder/reference) /[Configuratie en API](/hc/documentation/learn-dxpr-builder/reference/config-and-api) # API 端点. Learn DXPR BuilderReferenceConfiguratie en API ## In this guide Related guides - [配置参考](/zh-hans/hc/documentation/learn-dxpr-builder/reference/config-reference) - [API 参考](/zh-hans/hc/documentation/learn-dxpr-builder/development/api) - [Hooks API 参考](/zh-hans/hc/documentation/learn-dxpr-builder/development/hooks-api) 本页列出 DXPR Builder 在以下位置注册的每个路由 `dxpr_builder.routing.yml`，含控制器实现的 HTTP 方法、访问要求、请求参数和响应结构。编辑器的 JavaScript 是 AJAX 端点的预期客户端；本页没有任何稳定的公开 API，参数名称可能在版本之间变化。 ## 访问要求 路由使用三种要求。一个路由可以组合它们。 | 要求 | 含义 | |---|---| | `_permission` | 用户需要命名的 Drupal 权限。DXPR Builder 定义 `administer dxpr builder configuration`, `edit with dxpr builder` 和 `administer dxpr_builder_profile` ： `dxpr_builder.permissions.yml`; `view media` 和 `administer site configuration` 来自核心。 | | `_csrf_token` | 请求必须在 `token` 查询参数中携带有效的 CSRF 令牌。对于主 AJAX 处理器，编辑器从以下位置获取带令牌的网址 `/dxpr_builder/csrf` （或从 `dxpr_builder_csrf` 操作）。对于其他路由，字段格式化器将带令牌的网址放入 `drupalSettings.dxprBuilder`，例如 `fileUploadUrl`, `entityLinkSuggestionsUrl`, `userSettingsUrl` 和 `aiAgent.endpointUrl`. | | `_dxpr_builder_billable_user` | 用户必须是付费用户，如下定义。 | ### “billable user”（计费用户）的含义 `DxprBuilderBillableUserAccessCheck` 在 `DxprBuilderLicenseService::isBillableUser()` 对当前账户返回 true 时允许访问。该方法对被阻止的账户以及设置了 `dxpr_user_is_disavowed` 字段的账户（管理员在 User Licenses 页面排除了该用户的编辑）返回 false。其他情况下，对用户 1 以及持有 `edit with dxpr builder` 权限的任何账户返回 true。简言之，计费用户是允许使用 DXPR Builder 编辑的活跃未排除账户，许可服务将这些账户计入您的产品密钥。 ### HTTP 方法 路由在以下位置声明 `methods`，仅路由这些方法。未声明处，路由接受任何方法（Drupal 的 `MethodFilter` 仅过滤声明方法的路由。下表说明源码中可见时编辑器 JavaScript 实际使用的方法。 ## 编辑器 AJAX 端点 ### CSRF 令牌网址 | | | |---|---| | 路径 | `/dxpr_builder/csrf` | | 路由 | `dxpr_builder.csrf_refresh` | | 方法 | 未声明（任何方法）。编辑器发送 GET（`backend-connect.js`, `fetchCsrfTokenUrl()`). | | 要求 | 计费用户 | | 控制器 | `AjaxController::ajaxRefresh()` | 请求必须携带标头 `X-Requested-With: XMLHttpRequest`；否则控制器返回 HTTP 403 及 JSON 正文 `{"error": "Invalid request"}`。 | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `enterprise` | 查询字符串 | 可选 | 设为 `true` 和 `dxpr_builder_e` 模块已安装，令牌为以下内容生成 `dxpr_builder_e.ajax_callback` 路由。当设为 `true` 无该模块时控制器抛出异常。 | 响应：带主 AJAX 处理器网址的 JSON 字符串，以及 `token` 查询参数。该网址是从网站根开始的路径（包含基础路径，无主机）。JavaScript 将每个页面构建器操作发送到此网址。 ### 主 AJAX 处理器 | | | |---|---| | 路径 | `/dxpr_builder/ajax` | | 路由 | `dxpr_builder.ajax_callback` | | 方法 | 未声明（任何方法）。控制器从 POST 正文读取每个参数，编辑器发送 POST。 | | 要求 | 计费用户，CSRF 令牌 | | 控制器 | `AjaxController::ajaxCallback()` | POST 正文的 `action` 字段选择操作。每个操作及其参数列在[主 AJAX 处理器操作](#main-ajax-handler-operations)下。当 `action` 缺失或未知时，控制器返回不带命令的空 Drupal `AjaxResponse`。大多数重新检查计费用户状态的操作在该检查失败时返回同样的空响应；表中有两处例外。 ### AI 对话 | | | |---|---| | 路径 | `/dxpr_builder/ajax/ai/chat` | | 路由 | `dxpr_builder.ai_chat` | | 方法 | POST | | 要求 | `edit with dxpr builder`，计费用户，CSRF 令牌 | | 控制器 | `AiChatController::chat()` | 请求正文为 JSON。控制器将请求代理到 `dxpr` 所属 Drupal `ai` 模块，因此 API 密钥不到达浏览器。调用前合并来自以下位置的域名 `ai_output_allowed_domains` 设置到 `ai` 模块的主机名过滤器（该服务存在时）。值为 `*` 将过滤器设为完全信任。过滤器之后恢复。 | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `messages` | JSON 正文 | 必填 | 包含以下内容的对象数组 `role` 和 `content`. | | `stream` | JSON 正文 | 可选 | 布尔值，默认为 `true`. | | `model` | JSON 正文 | 可选 | 默认值 `kavya-m1`. | | `prediction` | JSON 正文 | 可选 | 以数组形式传递到提供方配置。 | | `providers` | JSON 正文 | 可选 | 透传到提供方配置。 | | `allowed_html_tags` | JSON 正文 | 可选 | 透传到提供方配置。 | | `allowed_html_classes` | JSON 正文 | 可选 | 透传到提供方配置。 | | `web_search` | JSON 正文 | 可选 | 仅转发 `false` 值；其他值均被忽略。 | | `response_format` | JSON 正文 | 可选 | 以数组形式传递到提供方配置。 | 响应： | 情形 | 状态 | 正文 | |---|---|---| | 流式（`stream` 为 true 且提供方流式传输） | 200, `Content-Type: text/event-stream` | 服务器发送事件。每个事件是 `data: ` 其中 JSON 含 `choices[0].delta.content` ，当提供方提供时， `id`, `object`, `created`, `model`, `original_model` 和 `usage`。流以以下内容结尾 `data: [DONE]`. | | 非流式 | 200, `application/json` | `{"choices": [{"message": {"role": "assistant", "content": ""}}]}` | | 正文不是 JSON，或 `messages` 缺失或为空 | 400, plain text | `Invalid request: messages required` | | `model` 不在 `allowed_models` 列表 `ai_provider_dxpr.settings` （仅在 `ai_provider_dxpr` 模块已安装且列表已设置） | 403, `application/json` | `{"error": {"code": "model_not_allowed", "message": "The selected model is not allowed. Please refresh the page to update your model options."}}` | | 提供方异常 | 500, `application/json` | `{"error": {"message": "The request could not be completed."}}` | ### AI 图像生成 | | | |---|---| | 路径 | `/dxpr_builder/ajax/ai/image` | | 路由 | `dxpr_builder.ai_image` | | 方法 | POST | | 要求 | `edit with dxpr builder`，计费用户，CSRF 令牌 | | 控制器 | `AiImageController::generate()` | | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `prompt` | JSON 正文 | 必填 | 文本提示词。 | | `model` | JSON 正文 | 可选 | 默认值 `kavya-image`. | | `size` | JSON 正文 | 可选 | 非空时转发到提供方配置。 | | `quality` | JSON 正文 | 可选 | 非空时转发到提供方配置。 | | `background` | JSON 正文 | 可选 | 非空时转发到提供方配置。 | 响应： | 情形 | 状态 | 正文 | |---|---|---| | Success | 200 | `{"data": [{"b64_json": ""}]}` （仅返回所生成图像的首张） | | 正文不是 JSON，或 `prompt` 缺失 | 400 | `{"error": {"message": "Invalid request: prompt required"}}` | | 提供方未返回图像 | 500 | `{"error": {"message": "No image was generated"}}` | | 提供方异常 | 500 | `{"error": {"message": "Image generation failed. Please try again."}}` | ### AI 图像编辑 | | | |---|---| | 路径 | `/dxpr_builder/ajax/ai/image/edit` | | 路由 | `dxpr_builder.ai_image_edit` | | 方法 | POST | | 要求 | `edit with dxpr builder`，计费用户，CSRF 令牌 | | 控制器 | `AiImageController::edit()` | | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `prompt` | JSON 正文 | 必填 | 编辑指令。 | | `image` | JSON 正文 | 必填 | Base64 编码的源图像（严格解码）。 | | `mimeType` | JSON 正文 | 可选 | 默认为 `image/png`；子类型成为传给提供商的文件扩展名。 | | `model` | JSON 正文 | 可选 | 默认值 `kavya-image`. | | `size`, `quality`, `background` | JSON 正文 | 可选 | 非空时转发到提供方配置。 | 响应： | 情形 | 状态 | 正文 | |---|---|---| | Success | 200 | `{"data": [{"b64_json": ""}]}` | | 正文不是 JSON，或 `prompt` 或 `image` 缺失 | 400 | `{"error": {"message": "Invalid request: prompt and image required"}}` | | `image` 不是有效的 base64 | 400 | `{"error": {"message": "Invalid image data: base64 decode failed"}}` | | 提供方未返回图像 | 500 | `{"error": {"message": "No image was generated"}}` | | 提供方异常 | 500 | `{"error": {"message": "Image editing failed. Please try again."}}` | ### 文件上传 | | | |---|---| | 路径 | `/dxpr_builder/ajax/file_upload` | | 路由 | `dxpr_builder.ajax_file_upload_callback` | | 方法 | POST、DELETE（在路由中声明；控制器只有一个上传处理程序，没有单独的删除分支） | | 要求 | 计费用户，CSRF 令牌 | | 控制器 | `UploadFileController::fileUpload()` | | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `upload` | 以以下内容发送的 multipart 表单文件 `upload[]` | 必填 | 一个或多个上传文件。 | 控制器按客户端 MIME 类型的第一部分对每个文件排序到 `://dxpr_builder_images`, `dxpr_builder_videos` 或 `dxpr_builder_files`。图像需要 MIME 类型的扩展名 `image/gif`, `jpg`, `jpeg`, `png`, `webp`, `avif` 或 `svg`。视频需要以下之一 `video/webm`, `ogv`, `ogg`, `mp4` 或 `quicktime` （例如 `.mov`）。大小限制为 PHP 上传最大值。同名且 SHA-256 内容与用户可查看的现有托管文件相同的文件被复用而非再次保存。当 `media` 模块已安装且有名为以下内容的媒体类型 `image`, `media_image`, `video` 或 `media_video` 存在，则为该文件创建（或复用）已发布的媒体实体。文件用量记录在 `dxpr_builder` 模块。 响应： | 情形 | 状态 | 正文 | |---|---|---| | Success | 201 | JSON 数组，每个文件一个对象： `url` （绝对文件网址）， `uuid` 和 `id` （媒体实体存在时指媒体实体，否则指文件）， `fid` （文件 ID）， `entity_type` (`media` 或 `file`). | | No `upload` 文件 | 400 | `{"message": "No files were uploaded."}` | | 上传无效、目标不可写或保存失败 | 500 | `{"message": ""}` | | 验证失败（扩展名或大小） | 422 | `{"message": ""}` | | 文件名已被另一请求锁定 | 503 | `{"message": "File \"\" is already locked for writing."}` | ### 媒体库对话框 | | | |---|---| | 路径 | `/dxpr_builder/media-library` | | 路由 | `dxpr_builder.media_library` | | 方法 | 未声明（任何方法）。从查询字符串读取参数。 | | 要求 | `view media`; admin route | | 控制器 | `AjaxController::openImageMediaLibrary()` | | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `media_type` | 查询字符串 | 可选 | `image` （默认）或 `video`. | | `remaining_slots` | 查询字符串 | 可选 | 打开器接受的条目数；默认为 1。 | | `uuid` | 查询字符串 | 可选 | 传递给打开者，作为 `opener_parameters.uuid`. | 提供的媒体类型取决于 `media_browser` 设置：`media_library` 直接使用 `image` 或 `video` 媒体类型；`media_library_acquia_dam` 在该媒体类型存在时使用 `acquia_dam_image_asset` 或 `acquia_dam_video_asset`。 响应： | 情形 | 结果 | |---|---| | Success | 由以下构建的渲染数组 `MediaLibraryUiBuilder::buildUi()` 带打开器 `media_library.opener.dxpr_builder`。Drupal 将其渲染为用于 iframe 的 HTML 页面。 | | `media_library` 模块未安装 | 403, plain text `Media Library is not enabled. Please enable it to access this feature.` | | 不支持 `media_type` | 400, plain text `Unsupported media type "".` | | `media_browser` 设置没有可用的媒体类型 | 400, plain text `The "" settings is not supported.` | ### 帮助链接验证器 | | | |---|---| | 路径 | `/dxpr_builder/ajax/help_link_validator` | | 路由 | `dxpr_builder.ajax_help_link_validator` | | 方法 | 未声明（任何方法）。开发脚本 `dxpr_builder_dev.js` 发送带表单编码正文的 POST。 | | 要求 | 计费用户 | | 控制器 | `AjaxController::validateHelpLink()` | | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `help_link` | POST 正文 | 必填（有意义回答所需） | 仅 `http` 或 `https` 主机上的网址 `dxpr.com` 带以下开头的路径 `/documentation/` 会被检查。 | 响应：JSON 数组。 `[true]`（当对链接的 HEAD 请求（不跟随重定向）返回 200 时）；`[false]`（当 HTTP 客户端抛出异常时）； `[]` 在其他每种情况下，包括缺失参数、不匹配网址或非 200 状态。 ### 实体链接建议 | | | |---|---| | 路径 | `/dxpr_builder/entity-link-suggestions` | | 路由 | `dxpr_builder.entity_link_suggestions` | | 方法 | GET | | 要求 | `edit with dxpr builder`、CSRF token；`no_cache` 路由选项 | | 控制器 | `EntityLinkSuggestionsController::suggestions()` | | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `q` | 查询字符串 | 必填（结果所需） | 搜索文本，小写。以下值 `/node/123` 直接加载该实体。 | | `langcode` | 查询字符串 | 可选 | 宿主实体的语言；默认为当前语言。仅返回该语言可用的实体。 | Bundle 指在其 bundle info 中启用了 `ckeditor5_link_suggestions` 的那些；未配置时搜索所有节点 bundle。每个实体类型最多匹配 100 个实体，通过核心实体引用选择插件进行 `CONTAINS` 搜索。 响应： `{"suggestions": [...]}` 带私有可缓存性和 300 秒最大期限。每个建议有 `description`, `entity_type_id`, `entity_uuid`, `group`, `label` 和 `path`。当 `q` 无匹配时，数组含单个手动链接建议，带 `description`, `label` （小写后的输入）与 `path` （输入为有效网址时取输入本身，否则为空字符串）。当 `q` 为空， `suggestions` 为空数组。 ### 用户编辑器设置 | | | |---|---| | 路径 | `/dxpr_builder/user-settings` | | 路由 | `dxpr_builder.user_settings` | | 方法 | POST | | 要求 | `edit with dxpr builder`、CSRF token；`no_cache` 路由选项 | | 控制器 | `UserSettingsController::save()` | 用户更改自己的编辑器设置时编辑器发送此请求，例如在以下位置 **编辑器设置**。这些值与用户账户一起存储在 `user.data`，模块 `dxpr_builder`. | 参数 | 来源 | 必填 | 备注 | |---|---|---|---| | `controls_layout` | JSON 正文 | 必填（唯一的设置） | `element`, `breadcrumb` 或 `default`. `default` 移除用户选择，以便资料或网站设置生效。 | 响应： | 情形 | 状态 | 正文 | |---|---|---| | 已保存 | 200 | `{"settings": {"controls_layout": ""}}`：保存后的每个设置， `default` 用户未存储选择的位置。 | | 正文不是非空 JSON 对象，或名称或值无效 | 400 | `{"error": "Invalid setting or value."}`。不存储任何内容。 | ## 主 AJAX 处理器操作 所有操作都发送到 `/dxpr_builder/ajax`，令牌查询参数从 `/dxpr_builder/csrf` 获取。操作名称在 POST 正文的 `action` 字段中发送；其他参数均为 POST 正文段字段，除非另有说明。“Re-checks billable”列标记在 switch 内再次调用 `isBillableUser()` 的操作。当该检查失败时，它们返回上述空 `AjaxResponse`，除非行另有说明。 ### 会话和访问 | 操作 | 参数 | 重新检查计费 | 返回 | |---|---|---|---| | `dxpr_login` | None | No | JSON 布尔值：当前用户是否计费。 | | `dxpr_builder_csrf` | None | 是 | JSON 字符串：带以下内容的处理器网址 `token` 查询参数（与以下相同 `/dxpr_builder/csrf` 无 `enterprise` 选项）。 | ### 容器（用 DXPR Builder 格式化器渲染的字段） | 操作 | 参数 | 重新检查计费 | 返回 | |---|---|---|---| | `dxpr_get_container_types` | None | 是 | 以以下内容为键的 JSON 对象 `entity_type\|bundle` 带值 `entity_type - bundle`，默认视图显示使用该格式化器的每个束对应一个条目 `dxpr_builder_text` 至少一个字段上的格式化器。 | | `dxpr_get_container_names` | `container_type` (required, `entity_type\|bundle`) | 是（返回空 JSON 字符串而非空响应） | 以以下内容为键的 JSON 对象 `entity_id\|field_name` (or `entity_id\|field_name\|langcode` 可翻译实体）的值为 `entity label\|field label`。当 `container_type` 缺失，或计费检查失败，响应为空 JSON 字符串。 | | `dxpr_save_container` | `type`（必填，`entity_type\|bundle`）；`name`（必填，`entity_id\|field_name` 或 `entity_id\|revision_id\|field_name`）；`htmlContent`（必填，编码后的标记）；`lang`（可选，默认为网站默认语言） | 是 | 成功时 JSON 空字符串。当 `htmlContent` 不是字符串，或该语言不适用于不可翻译实体时，返回带 JSON 消息的 HTTP 400；请求的翻译不存在时返回 404；实体无法加载时返回 500。 | `dxpr_save_container` 执行以下操作： 1. 解码 `htmlContent`：将每个字节与 7 异或，然后 URL 解码。 2. 将结果写入命名字段的第一个增量。 3. 创建带日志消息的新默认修订 `Saved with DXPR builder` 当实体类型可修订时。 4. 移除实体的所有内容锁定。 5. 更新 `block_revision_id` 引用已保存内联区块的 Layout Builder 版块中。 6. 递增 `dxpr_builder.saves_count` 状态值。 仅当用户具有以下条件时保存 `update` 访问该实体。没有它，操作仍返回空字符串成功响应。 ### CMS 元素（区块和视图） | 操作 | 参数 | 重新检查计费 | 返回 | |---|---|---|---| | `dxpr_builder_get_cms_element_names` | None | 是 | 来自以下内容的 JSON 对象 `DxprBuilderService::getCmsElementNames()` 带键 `list`, `disallowed` 和 `blockCategories`. | | `dxpr_get_cms_element_settings` | `name` (required): `view--` 或 `block-`；`ajax_page_state[libraries]`（可选，已加载库的逗号分隔列表） | 是 | 带以下内容的 JSON 对象 `css`, `js`, `settings` 和 `data`。对于视图，`data` 是渲染后的公开筛选器小部件；对于区块，`data` 是包裹在 `
` 标签中的区块配置表单，其中 `provider`、`admin_label`、`label`、`label_display` 和 `context_mapping` 元素被移除，所有 details 元素被打开。 | | `dxpr_builder_load_cms_element` | `name`（必填，由 `parseStringForCmsElementInfo()` 解析）；`settings`（必填）；`data`（必填，数组）；`ajax_page_state[libraries]`（可选） | No | 带以下内容的 JSON 对象 `css`, `js`, `settings` 和 `data`，其中 `data` 是渲染后的区块或视图显示。 | 在两个返回 `settings`的操作中， `css` 和 `js` 是页面中尚不存在的已渲染资源标签，以及 `settings` 是解码后的 `drupalSettings` 对象，没有时为空字符串。 ### 页面模板 | 操作 | 参数 | 重新检查计费 | 返回 | |---|---|---|---| | `dxpr_get_page_templates` | None | 是 | 已启用页面模板的 JSON 数组，每个带 `title`, `uuid`, `module` （始终 `null`：（实体不存储它）， `category`, `date`, `weight` （整数）与 `image` （ `data:` 网址，或模块的 `not-found.png` 网址）。 | | `dxpr_load_page_template` | `uuid` (required) | 是 | 包含模板标记（基础令牌已替换）的 HTML 响应；没有启用的模板匹配时为空。 | ### 用户模板 | 操作 | 参数 | 重新检查计费 | 返回 | |---|---|---|---| | `dxpr_get_templates` | None | 是 | 当前用户拥有或标记为 global 的模板 JSON 数组；作者账户已不存在的模板除外。每个条目有 `id`、`uuid`、`name`、`global`、`current_user_is_author`、`author_id`、`author_name`、`type`，存储时还有 `image`（`data:` URL）。 | | `dxpr_load_template` | `uuid` (required) | 是 | 包含模板标记（基础令牌已替换）的 HTML 响应；没有启用的模板匹配时为空。 | | `dxpr_save_template` | `name`（必填）；`template`（必填，markup）；`type`（可选，默认为 `custom`）；`global`（可选，转为 boolean）； `image`（可选：POST 正文中的 base64 字符串或 `data:image` 网址，或名为 `image` 的多部分文件字段） | 是 | 带 `message` 和 `code` 的 JSON 对象。成功时 `code` 为 200；存在同名机器名的模板时 `code` 为 409（HTTP 状态 200）；图像不是有效图像数据时返回 `code` 400 及 HTTP 400。 | | `dxpr_delete_template` | `name` (required) | 是 | JSON 空字符串。 | 机器名派生自 `name` 将其小写，并替换以下范围之外的每个字符序列 `a-z0-9_` 带下划线。 `type` 回退到 `data-azb` 标记中的属性，当存储的模板没有类型时 ### Images | 操作 | 参数 | 重新检查计费 | 返回 | |---|---|---|---| | `dxpr_builder_get_image_urls` | `entityIDs`（必填，数组）；`imageStyle`（必填；unstyled 文件用 `original`）；`entityType`（必填；`media` 解析媒体条目，任何其他值用作 ID 的实体类型） | 是 | 文本正文：逗号分隔的图像网址。文件给出带以下内容的根相对网址 `fid` 查询参数。以下内容的媒体条目 `image` 或 `video` 类型解析到其源文件。 `acquia_dam_image_asset` 条目提供带以下内容的 DAM 网址 `mid`, `acquiaDamAsset` 和 `imageStyle` 已添加。跳过其他媒体条目。以下情况返回无正文的 HTTP 204 `entityIDs` 为空，或无法解析媒体条目时。 | | `dxpr_builder_get_image_style_url` | `imageStyle` (required); `entityId` (required); `entityTypeId` (required, `file` 或 `media`) | 是 | 文本正文。对于文件：通过图像样式的根相对网址（SVG 文件和 `original` 跳过样式），带 `fid` 查询参数。对于 `acquia_dam_image_asset` 媒体条目：DAM 网址。其他实体或未找到实体时 HTTP 204 无正文。 | | `dxpr_builder_get_image_metadata` | `entityId` (required); `entityType` (required, `file` 或 `media`) | 是（返回 403 JSON 而非空响应） | `{"data": {"alt": "...", "title": "..."}}` 来自媒体条目的图像源字段（Acquia DAM 资源提供其 DAM 替代文本和空标题）。对于文件，值来自第一个媒体条目，该条目 `field_media_image` 引用它。 `data` 当实体既非文件也非媒体条目，或没有媒体引用该文件时为空数组。错误：400 `{"error": "Missing required parameters"}`, 404 `{"error": "Entity not found"}`, 500 `{"error": "Failed to load entity"}`, 403 `{"error": "Access denied"}`. | ### 内容锁定 | 操作 | 参数 | 重新检查计费 | 返回 | |---|---|---|---| | `dxpr_content_lock_status` | `entity_id`, `revision_id`, `entity_type`, `langcode` （均为必填） | No | 带以下内容的 JSON 对象 `status` （布尔值）与 `label`（实体标签）；锁定时还有 `entity_lock_author_id` 和 `entity_lock_author_name`。 | | `dxpr_toggle_content_lock` | `entity_id`, `revision_id`, `entity_type`, `langcode`, `toggle_action`（均为必填；`lock` 创建锁定，任何其他值移除锁定） | No | 带以下内容的 JSON 对象 `label` 和 `status` (`true` 锁定后， `false` 解锁后）。空 JSON 数组（`[]`）（当实体无法加载或用户缺少 `update` 访问权限。 | ## 管理页面 所有这些路由接受任何方法（无 `methods` 键）。包含以下内容的路径 `{...}` 取配置实体 ID，或迁移 ID，用于 `{migration_id}`. | 路径 | 路由 | 权限 | 用途 | |---|---|---|---| | `/admin/dxpr_studio` | `dxpr_builder.admin.studio` | `administer dxpr builder configuration` | DXPR Studio 概览；列出子页面的核心管理菜单区块页面。 | | `/admin/dxpr_studio/dxpr_builder` | `dxpr_builder.admin.studio.builder` | `administer dxpr builder configuration` | DXPR Builder 概览；核心管理菜单区块页面。 | | `/admin/dxpr_studio/dxpr_builder/settings` | `dxpr_builder.settings` | `administer dxpr builder configuration` | `DxprBuilderSettingsForm`：模块设置表单。 | | `/admin/dxpr_studio/dxpr_builder/ai_settings` | `dxpr_builder.ai_settings` | `administer dxpr builder configuration` | `DxprBuilderAiSettingsForm`：AI 设置表单。 | | `/admin/dxpr_studio/dxpr_builder/user_templates` | `entity.dxpr_builder_user_template.collection` | `administer site configuration` | 列表 `dxpr_builder_user_template` 配置实体。 | | `/admin/dxpr_studio/dxpr_builder/user_templates/add` | `entity.dxpr_builder_user_template.add_form` | `administer site configuration` | 添加用户模板。 | | `/admin/dxpr_studio/dxpr_builder/user_templates/{dxpr_builder_user_template}` | `entity.dxpr_builder_user_template.edit_form` | `administer site configuration` | 编辑用户模板。 | | `/admin/dxpr_studio/dxpr_builder/user_templates/{dxpr_builder_user_template}/delete` | `entity.dxpr_builder_user_template.delete_form` | `administer site configuration` | 删除用户模板（确认表单）。 | | `/admin/dxpr_studio/dxpr_builder/page_template` | `entity.dxpr_builder_page_template.collection` | `administer site configuration` | 列表 `dxpr_builder_page_template` 配置实体。 | | `/admin/dxpr_studio/dxpr_builder/page_template/add` | `entity.dxpr_builder_page_template.add_form` | `administer site configuration` | 添加页面模板。 | | `/admin/dxpr_studio/dxpr_builder/page_template/create` | `dxpr_builder.create_page_template` | `administer dxpr builder configuration` | `PageController::createPageTemplate()`：复制以下位置标识的已启用用户模板 `uuid` 查询参数，创建 ID 和分类相同的新页面模板 `DXPR`。它设置状态或错误消息并重定向到用户模板列表。 | | `/admin/dxpr_studio/dxpr_builder/page_template/{dxpr_builder_page_template}` | `entity.dxpr_builder_page_template.edit_form` | `administer site configuration` | 编辑页面模板。 | | `/admin/dxpr_studio/dxpr_builder/page_template/{dxpr_builder_page_template}/delete` | `entity.dxpr_builder_page_template.delete_form` | `administer site configuration` | 删除页面模板（确认表单）。 | | `/admin/dxpr_studio/dxpr_builder/profile` | `entity.dxpr_builder_profile.collection` | `administer dxpr_builder_profile` | 列表 `dxpr_builder_profile` 配置实体。 | | `/admin/dxpr_studio/dxpr_builder/profile/add` | `entity.dxpr_builder_profile.add_form` | `administer dxpr_builder_profile` | 添加资料。 | | `/admin/dxpr_studio/dxpr_builder/profile/{dxpr_builder_profile}` | `entity.dxpr_builder_profile.edit_form` | `administer dxpr_builder_profile` | 编辑资料。 | | `/admin/dxpr_studio/dxpr_builder/profile/{dxpr_builder_profile}/delete` | `entity.dxpr_builder_profile.delete_form` | `administer dxpr_builder_profile` | 删除资料（确认表单）。 | | `/admin/dxpr_studio/dxpr_builder/user_licenses` | `dxpr_builder.user_licenses` | `administer dxpr builder configuration` | `PageController::userLicensesPage()`：已许可用户的未缓存表（列为 User、Roles、Sites、Assigned 和 Operations）。其上方页面渲染自己的许可证摘要卡（`dxpr-license-info`）。有许可信息时，在释放的许可等待 30 天期间，显示 "Next license available on" 通知。在此路由上 **许可信息** 区块不渲染任何内容，因此摘要不会显示两次。 | | `/admin/dxpr_studio/dxpr_builder/user_licenses/sites` | `dxpr_builder.user_licenses.sites` | `administer dxpr builder configuration` | `PageController::userLicensesSitesPage()`：`mail` 请求参数中给出用户的已记录域名条目列表；从许可证表格经弹窗打开。 | | `/admin/dxpr_studio/dxpr_builder/content` | `dxpr_builder.licensed_content` | `administer dxpr builder configuration` | `PageController::licensedContentPage()`：使用 DXPR Builder 编辑的内容项的分页表（每页 20 个），附带内容项许可证摘要。查询参数 `needs_migration=1` 仅显示需要内容迁移的条目。无许可信息时为空。 | | `/admin/dxpr_studio/dxpr_builder/migration-status` | `dxpr_builder.migration_status` | `administer dxpr builder configuration` | `MigrationStatusController::statusPage()`：已注册内容迁移及其待定条目的未缓存表。每个待定迁移都有一个 **Run now** 链接，和 **Run all pending migrations** 按钮在有待定项时出现。 | | `/admin/dxpr_studio/dxpr_builder/migration-run/{migration_id}` | `dxpr_builder.migration_run_confirm` | `administer dxpr builder configuration` | `MigrationRunConfirmForm`：确认，然后将一个迁移作为一批运行并返回状态页面。 | | `/admin/dxpr_studio/dxpr_builder/migration-run-all` | `dxpr_builder.migration_run_all_confirm` | `administer dxpr builder configuration` | `MigrationRunAllConfirmForm`：确认，然后将所有已注册迁移作为一批运行并返回状态页面。 | | `/dxpr-builder/disavow-user` | `dxpr_builder.disavow_user_confirm` | `administer dxpr builder configuration` | `DisavowUserConfirmForm`：确认排除以下位置给出的用户 `uid` 查询参数，以排除用户参与 DXPR Builder 编辑。 | | `/dxpr-builder/delete-stale-user` | `dxpr_builder.delete_stale_user_confirm` | `administer dxpr builder configuration` | `DeleteStaleUserConfirmForm`：确认移除以下位置给出电子邮件地址的许可证数据 `email` 查询参数。 | ## 接下来做什么？ - [配置参考](/zh-hans/hc/documentation/learn-dxpr-builder/reference/config-reference) 了解控制这些端点所用媒体浏览器和 AI 行为的设置。 - [PHP API](/zh-hans/hc/documentation/learn-dxpr-builder/development/api) 了解控制器调用的服务。 - [Hooks API](/zh-hans/hc/documentation/learn-dxpr-builder/development/hooks-api) 了解让其他模块改变页面构建器行为的钩子。