Интеграция ACF с WP REST API

Обзор

Начиная с версии 5.11, ACF поддерживает просмотр и управление произвольными полями через WordPress REST API. Это позволяет разработчикам получать и редактировать данные произвольных полей с помощью стандартных эндпоинтов WP REST API или создавать произвольные темы на React, Vue и других JavaScript-библиотеках.

Эндпоинты

Любые группы произвольных полей, добавленные к данным WordPress — например, записям (включая произвольные типы записей), пользователям и рубрикам (включая произвольные таксономии), — будут доступны в соответствующих эндпоинтах WP REST API:

• /{post-type}
  • posts, pages, custom-post-types и т. д.
• /{post-type}/{post_id}
• /{post-type}/{post_id}/revisions
• /{post-type}/{post_id}/revisions/{revision_id}
• /{post-type}/{post_id}/autosaves
• /{post-type}/{post_id}/autosaves/{autosave_id}
• /users
• /users/{user_id}
• /users/me
• /categories
• /categories/{category_id}
• /{custom-taxonomy}/{term_id}

Включение REST API для полей ACF

По умолчанию группы полей не отображаются в WP REST API. Чтобы они появились в API, необходимо явно включить эту возможность.

Видимость группы полей в REST API можно включить в разделе «Настройки». Откройте вкладку Group Settings, а затем включите параметр Show in REST API.

Использование REST API с произвольными типами записей и таксономиями

По умолчанию произвольные типы записей и таксономии, созданные в ACF, доступны в WP REST API. Для них используются пространство имён wp/v2 и классы контроллеров WP_REST_Posts_Controller для типов записей и WP_REST_Terms_Controller для таксономий.

Чтобы изменить видимость или настройки REST API для произвольного типа записи, перейдите в ACF > Post Types и выберите или зарегистрируйте произвольный тип записи. Включите Advanced Configuration, чтобы открыть дополнительные настройки. На вкладке REST API доступны параметры видимости, пространства имён и класса контроллера. Здесь также можно создать базовый URL для URL REST API типа записи.

Аналогичный процесс применяется к произвольным таксономиям.

Методы запросов

Для работы с данными ACF можно использовать следующие три метода запросов:

1. Запросы GET позволяют просматривать данные ACF.
2. Запросы OPTIONS позволяют просматривать схему данных ACF.
3. Запросы POST позволяют обновлять любые поля ACF и требуют аутентификации.

Запрос GET

Запрос GET возвращает данные ACF в ответе REST API.

В следующем примере настроен произвольный тип записи book и группа полей ACF для всех книг с полями Author (Text), Author Bio (WYSIWYG) и Author Image (Image). Для каждой книги будут заполнены данные этих произвольных полей.

Запрос GET к https://hellfish.media/wp-json/wp/v2/book/{ID}, где {ID} — идентификатор книги, возвращает данные произвольных полей в JSON-объекте acf, сразу после данных template.

{
  "acf": {
    "author": "Abraham Simpson",
    "author_bio": "...",
    "author_image": 3949
  }
}

Запрос OPTIONS

Запрос OPTIONS к эндпоинту WordPress REST API позволяет просмотреть схему объекта данных, то есть доступные поля и их свойства. Для полей ACF он показывает подробности настройки поля. Например, для текстового поля в схеме может отображаться ограничение «Max Length». Дополнительную информацию см. в разделе «Типы полей REST API».

В нашем примере запрос OPTIONS возвращает схему книги, включая данные настроенных полей ACF.

{
  "acf": {
    "description": "ACF field data",
    "type": "object",
    "properties": {
      "author": { "type": ["string", "null"], "required": false },
      "author_bio": { "type": ["string", "null"], "required": false },
      "author_image": { "type": ["integer", "null"], "required": false }
    },
    "required": false
  }
}

Запрос POST

Запрос POST позволяет изменять данные книги. В нашем случае можно обновить поля ACF author, author_bio и author_image. Поскольку POST изменяет данные, запрос необходимо аутентифицировать одним из доступных методов аутентификации. Для обновления групп полей ACF передайте данные в JSON-кодированном объекте acf, используя ту же структуру, что и в ответе GET:

{
  "acf": {
    "author": "Abraham (Abe) Simpson"
  }
}

Пример выполнения POST-запроса через JavaScript с использованием утилиты WordPress apiFetch:

import apiFetch from '@wordpress/api-fetch';

// POST
apiFetch( {
  path: '/wp/v2/book/{ID}',
  method: 'POST',
  data: {
    "acf": {
      "author": "Abraham (Abe) Simpson",
    }
  },
} ).then( ( res ) => {
  console.log( res );
} );

В результате объект acf книги будет обновлён.

Передача значения null удаляет содержимое поля:

import apiFetch from '@wordpress/api-fetch';

// POST
apiFetch( {
  path: '/wp/v2/book/{ID}',
  method: 'POST',
  data: {
    "acf": {
      "author_bio": null
    }
  },
} ).then( ( res ) => {
  console.log( res );
} );

После этого объект acf книги будет выглядеть так:

{
  "acf": {
    "author": "Abraham (Abe) Simpson",
    "author_bio": "",
    "author_image": 3949
  }
}

Аутентификация

Поскольку ACF использует стандартные эндпоинты WP REST API, по умолчанию применяются стандартные методы аутентификации WordPress — cookies и nonce. Поэтому при разработке в панели управления WordPress код выполняется в уже авторизованной сессии, и отдельная аутентификация не требуется.

Если REST API используется за пределами авторизованной сессии, например в JavaScript-приложении, необходимо аутентифицировать POST-запросы. Для этого можно использовать пароли приложений, доступные в ядре WordPress, или плагин JSON Web Tokens.

Типы полей REST API

В таблице перечислены все типы полей ACF, поддерживаемые WP REST API.

Примечания для разработчиков

Отключение системы ACF REST API

Поддержку WP REST API можно полностью отключить, вернув false в фильтре acf/settings/rest_api_enabled. Это переопределит настройки «Show in REST API» для групп полей и полностью отключит поддержку WP REST API в ACF:

add_filter( 'acf/settings/rest_api_enabled', '__return_false' );

Расширение системы REST API

Ограничение отображаемых полей с помощью параметра запроса _fields

Параметр запроса WP REST API ?_fields позволяет запросить только объект acf или отдельные поля внутри него.

// Вернуть объект acf и все доступные поля:

/wp-json/wp/v2/book/{ID}?_fields=acf

// Вернуть только отдельные поля объекта acf:

/wp-json/wp/v2/book/{ID}?_fields=acf.author,acf.author_bio

// Вернуть конкретное подполе определённого группового поля:

/wp-json/wp/v2/book/{ID}?_fields=acf.author_meta.profile_url

Управление форматом вывода

Параметр acf_format в запросе WP REST API позволяет изменить формат вывода ответа.

По умолчанию используется значение light. Оно передаёт значения полей методу format_value_for_rest() объекта конкретного типа поля перед формированием ответа. Такое форматирование минимально, а результат остаётся близким к исходным данным и схеме.

Передача значения standard заставляет все поля форматироваться глобальной функцией ACF acf_format_value():

/wp-json/wp/v2/book/{ID}?_fields=acf&acf_format=standard

При использовании standard поле author_image будет содержать дополнительные сведения об изображении, например его ID, URL, размеры и доступные размеры.

Чтобы установить стандартный формат для всех данных ответа, используйте фильтр acf/settings/rest_api_format:

add_filter( 'acf/settings/rest_api_format', function () {
    return 'standard';
} );

Если требуется дополнительное форматирование значения поля ACF для WP REST API, используется фильтр acf/rest/format_value_for_rest:

return apply_filters( 'acf/rest/format_value_for_rest', $value_formatted, $post_id, $field, $value, $format );

С его помощью можно изменить формат или вывод значения поля. Например, следующий фрагмент добавляет label поля в объект каждого значения acf:

add_filter('acf/rest/format_value_for_rest', function ($value_formatted, $post_id, $field, $value, $format){
    return array(
        $field['label'] => $value_formatted
    );
}, 10, 5);

Фильтр также можно применять к отдельным типам полей или к полям по имени и ключу.

Для всех полей типа text:

add_filter('acf/rest/format_value_for_rest/type=text', function ($value_formatted, $post_id, $field, $value, $format){
    // return the overridden value
}, 10, 5);

Для поля с именем author:

add_filter('acf/rest/format_value_for_rest/name=author', function ($value_formatted, $post_id, $field, $value, $format){
    // return the overridden value
}, 10, 5);

Для поля с ключом field_123456789:

add_filter('acf/rest/format_value_for_rest/key=field_123456789', function ($value_formatted, $post_id, $field, $value, $format){
    // return the overridden value
}, 10, 5);

Фильтрация полей, отображаемых на любом эндпоинте

Фильтр acf/rest/get_fields позволяет управлять полями, которые отображаются или доступны для обновления. Параметр $http_method можно использовать для изменения набора полей в зависимости от метода запроса — GET, POST или OPTIONS:

add_filter( 'acf/rest/get_fields', function ( $fields, $resource, $http_method ) {
    // Измените и верните здесь массив $fields.
    return $fields;
}, 10, 3 );

Управление встраиваемыми ссылками REST API

GET-запросы к объектам с некоторыми типами полей также содержат встраиваемую ссылку — URL, указывающий на другой ресурс. Например, поле User добавляет ссылку на выбранного пользователя в секцию _links ответа REST API:

"acf:user": [
  {
    "embeddable": true,
    "href": "https://hellfish.media/wp-json/wp/v2/users/1"
  }
]

Чтобы упростить ответ REST API, можно отключить обработчик встраиваемых ссылок с помощью фильтра acf/settings/rest_api_embed_links:

add_filter( 'acf/settings/rest_api_embed_links', '__return_false' );

Для более точного управления используйте фильтр acf/rest/get_field_links и его варианты type, name и key:

add_filter( 'acf/rest/get_field_links', function ( $links, $post_id, $field, $value ) {
    if ( $field['name'] === 'author' ) {
        return false;
    }

    return $links;
}, 10, 4 );

Управление схемой поля

WordPress использует схему для проверки и очистки входящих данных. Она также помогает внешним системам и сервисам понимать данные API. ACF создаёт схему для каждого ресурсного эндпоинта. Управлять схемой поля можно с помощью фильтра acf/rest/get_field_schema и его вариантов type, name и key:

add_filter( 'acf/rest/get_field_schema', function ( $schema, $field ) {
    if($field['type'] === 'number'){
        $schema['minimum'] = 1;
        $schema['maximum'] = 100;
        $schema['multipleOf'] = 1;
    }

    return $schema;
}, 10, 2 );

Дополнительную информацию о расширении WP REST API см. в документации по схемам.

Обновлено: 30.09.2026