自定义资源

有些站点可能不希望暴露某些 JSON:API 资源类型或字段，或希望重命名字段以提供更简洁的接口。

为允许进行这些更改，JSON:API 会以事件名 ResourceTypeBuildEvents::BUILD 派发一个 ResourceTypeBuildEvent 事件对象。请参阅订阅与派发事件以了解如何使用这些事件。

事件订阅器可以调用以下方法：

• ResourceTypeBuildEvent::disableResourceType()：阻止某个资源类型通过 JSON:API 以任何方式被访问。
• ResourceTypeBuildEvent::disableField()：阻止某个字段通过 JSON:API 以任何方式被访问。
• ResourceTypeBuildEvent::setPublicFieldName()：为字段设置别名，使 JSON:API 不再暴露内部的 Drupal 字段名。
• ResourceTypeBuildEvent::setResourceTypeName()：为资源类型设置别名，使 JSON:API 不再暴露内部的 Drupal 资源名。

任何模块（自定义或贡献模块）都可以为该事件实现订阅器。这意味着某个站点的专用模块可以禁用资源类型，同样地，提供自有实体类型的模块也可以禁用其对应的 JSON:API 表达形式。

示例

下面是一个 EventSubscriber 示例，展示了你可以采取的所有操作。

<?php

namespace Drupal\modules\custom\resource_types\EventSubscriber;

use Drupal\jsonapi\ResourceType\ResourceTypeBuildEvents;
use Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

/**
 * 针对部分资源类型进行更改的事件订阅器。
 */
class ResourceTypeBuildEventSubscriber implements EventSubscriberInterface {

  /**
   * {@inheritdoc}
   */
  public static function getSubscribedEvents() {
    return [
      ResourceTypeBuildEvents::BUILD => [
        ['disableResourceType'],
        ['aliasResourceTypeFields'],
        ['disableResourceTypeFields'],
        ['renameResourceType'],
      ],
    ];
  }

  /**
   * 禁用 node/page 资源类型。
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   构建事件对象。
   */
  public function disableResourceType(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--page') {
      $event->disableResourceType();
    }
  }

  /**
   * 将 body 字段设置别名为 content。
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   构建事件对象。
   */
  public function aliasResourceTypeFields(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--article') {
      foreach ($event->getFields() as $field) {
        if ($field->getInternalName() === 'body') {
          $event->setPublicFieldName($field, 'content');
        }
      }
    }
  }

  /**
   * 在 node--article 上禁用 sticky 字段。
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   构建事件对象。
   */
  public function disableResourceTypeFields(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--article') {
      foreach ($event->getFields() as $field) {
        if ($field->getInternalName() === 'sticky') {
          $event->disableField($field);
        }
      }
    }
  }

  /**
   * 将 node--article 重命名为 article，使资源以 /jsonapi/article 暴露。
   *
   * @param \Drupal\jsonapi\ResourceType\ResourceTypeBuildEvent $event
   *   构建事件对象。
   */
  public function renameResourceType(ResourceTypeBuildEvent $event) {
    if ($event->getResourceTypeName() === 'node--article') {
      $event->setResourceTypeName('article');
    }
  }

}

JSON:API 扩展（JSON:API Extras）

上述部分功能也由 JSON:API Extras 提供。该模块会在可能的情况下复用核心功能，同时提供一个界面以及一些额外特性，例如：

1. 修改 API 的基础路径（basepath）。
2. 为字段添加增强器（enhancers）。
3. 默认禁用资源。

启用该模块后，你可以访问 /admin/config/services/jsonapi 查看由 JSON:API 暴露的所有配置与内容列表。

文章来自 Drupal 文档。