API управління контентом Contentful (CMA): Масова завантаження та оновлення контенту - javascript.org.ua

Contentful, як платформа для управління контентом (CMS), пропонує надзвичайно гнучкий підхід для створення, управління та доставки контенту через різні канали. Для взаємодії з інформацією, що зберігається в Contentful, платформа надає кілька API, які відповідають різним потребам, від простих запитів до управління даними. У цій статті ми розглянемо різні способи роботи з інформацією в Contentful і зосередимося на використанні Content Management API (CMA), ідеальної для маніпулювання даними через проект Node JS.

Різні способи взаємодії з Contentful

Content Delivery API (CDA):
CDA — це найбільш використовувана API для споживання опублікованого контенту. Вона ідеально підходить для фронтенд-застосунків, які мають відображати контент для користувачів.
Se accede a través de solicitudes REST o GraphQL y es de solo lectura, lo que garantiza seguridad y estabilidad para el contenido público.
GraphQL API:
Contentful пропонує реалізацію GraphQL для більш гнучких і специфічних запитів. Ця API дозволяє розробникам отримувати саме ті дані, які їм потрібні, з меншим об'ємом відповіді, оптимізуючи продуктивність у веб- або мобільних застосунках.
Content Preview API:
Ця API призначена для показу контенту в чернетці або неопублікованого. Вона корисна в середовищах, де потрібно переглядати зміни перед їх публікацією.
Content Management API (CMA):
CMA — це найпотужніший та найуніверсальніший інструмент для взаємодії з Contentful через скрипти. Вона дозволяє створювати, читати, оновлювати та видаляти контент програмним способом.
Está diseñada para automatizar flujos de trabajo, gestionar contenido a gran escala y construir herramientas personalizadas.

Enfoque en la Content Management API (CMA)

CMA виділяється як ключове рішення, коли потрібно здійснювати прямі зміни в контенті, збереженому в Contentful. На відміну від CDA, яка є лише для читання, CMA дозволяє маніпулювати даними, такими як:

Створення нових записів і активів.
Динамічне оновлення існуючого контенту.
Видалення застарілих або не використовуваних даних.
Керування середовищами (environments) і користувачами.

Переваги CMA

Автоматизація повторюваних завдань: Ідеально підходить для завантаження великих обсягів контенту або синхронізації даних з інших джерел.
Повна гнучкість: Можна інтегрувати власні скрипти, що підходять для специфічних потреб вашого проекту.
Розширене управління: Повний контроль над записами, активами, налаштуваннями простору та іншими аспектами.
4.
Масштабованість: Ідеально підходить для великих команд або проєктів з складними потоками контенту.

Приклади використання Content Management API (CMA) в Contentful

Content Management API (CMA) від Contentful — потужний інструмент, що дозволяє автоматизувати та персоналізувати управління контентом програмним способом. Нижче ми розглянемо деякі поширені випадки використання, де CMA може суттєво змінити ситуацію, спрощуючи складні завдання та покращуючи ефективність управління контентом.

Масове завантаження контенту: В проєктах, де необхідно імпортувати великі обсяги контенту, такі як продукти, статті або описи, CMA є ідеальним варіантом.
Наприклад, скрипт може зчитувати дані з електронної таблиці або зовнішньої бази даних і автоматично завантажувати їх у Contentful як записи з правильними полями та типами контенту.
Синхронізація з зовнішніми системами: Якщо ви керуєте контентом, який має бути синхронізований з іншими системами, такими як ERP або CRM, CMA може допомогти. Скрипт може оновлювати записи в Contentful щоразу, коли в цих системах відбуваються зміни, наприклад, нові продукти, зміни в цінах або оновлення описів.
Генерація динамічних записів: У динамічних проєктах, таких як додатки, що генерують блоги з зовнішніх даних, CMA дозволяє створювати записи на основі API третіх сторін.
Це корисно для синхронізації контенту в реальному часі або автоматизації публікацій.

Давайте застосуємо це на практиці: змінюємо інформацію через CMA

Мета:

За допомогою проєкту на Node.js ми завантажимо п’ять продуктів з файлу Excel у ваш обліковий запис Contentful, використовуючи заздалегідь визначену модель контенту. Після цього буде оновлено назву кожного продукту, додавши до нього персоналізований префікс.

Вимоги:

Активний обліковий запис на Contentful з доступом до простору.
Налаштована модель контенту з необхідними полями.
Редактор коду, наприклад, Visual Studio Code або подібний.
Встановлений Node.js на системі.

Щоб почати взаємодіювати з Content Management API (CMA) на Contentful, спершу потрібно правильно налаштувати доступ. Це включає отримання токена доступу, ідентифікацію вашого простору та середовища, а також підготовку середовища для розробки.

1.

Створення проєкту на Node.js

Відкрийте термінал і перейдіть до папки, де хочете створити свій проєкт.
Виконайте наступну команду для ініціалізації нового проєкту на Node.js:

mkdir contentful-cma-example  
cd contentful-cma-example  
npm init -y

Це створить файл package.json з базовою конфігурацією проєкту.
Додайте поле type до файлу з значенням “module”, щоб використовувати модулі ECMAScript (ESM) замість системи модулів CommonJS.

{  
 "name": "contentful-cma-example",  
 "version": "1.0.0",  
 "main": "index.js",  
 "type": "module",  
 "scripts": {  
 "test": "echo \"Error: no test specified\" && exit 1"  
 },  
 "keywords": [],  
 "author": "",  
 "license": "ISC",  
 "description": ""  
}

Встановіть необхідні залежності:

npm install contentful-management dotenv xlsx

contentful-management: Офіційний SDK для взаємодії з CMA.

dotenv: Для безпечного керування змінними середовища.

xlsx: Для читання та обробки файлів Excel.

2.

Отримання токену доступу

Токен доступу — це ключ, який аутентифікує запити до API. Для його отримання дотримуйтесь наступних кроків:

Увійдіть у Contentful.
Перейдіть до простору, з яким ви будете працювати, і натисніть на іконку налаштувань, вибравши CMA Tokens.

Натисніть Create personal access token.

Заповніть поля, вибравши ім'я і дату закінчення терміну дії, після чого натисніть кнопку Generate.

Скопіюйте згенерований токен і збережіть його в безпечному місці. Цей токен має повні дозволи, тому не слід ділитися ним публічно.

3. Налаштування змінних середовища

Щоб захистити ваші облікові дані, збережіть їх у файлі .env.
У кореневому каталозі проєкту створіть файл з назвою .env із наступним вмістом:

CONTENTFUL_SPACE_ID=tu_space_id  
CONTENTFUL_ENVIRONMENT=master  
CONTENTFUL_MANAGEMENT_TOKEN=tu_token_de_gestion

SPACEID_ можна знайти, зайшовши в General settings у головному середовищі.

CONTENTFULENVIRONMENT_ — це середовище, в якому ви будете запитувати інформацію, а CONTENTFULMANAGEMENTTOKEN — це токен, який ми створили раніше.

4. Створення головного файлу

Створіть файл з назвою index.js у кореневому каталозі проєкту.
Цей файл буде точкою входу для скрипта та викликатиме файл з змінними середовища.

import dotenv from "dotenv";  
dotenv.config({ path: ".env" });

Також імпортуйте бібліотеку, яка дозволить нам взаємодіяти з Contentful.

import contentfulPkg from "contentful-management";  
const { createClient } = contentfulPkg;

Тепер викликайте змінні середовища у вашому файлі.

const spaceId = process.env.CONTENTFUL_SPACE_ID;  
const envId = process.env.CONTENTFUL_ENVIRONMENT;  
const accessTokenCMA = process.env.CONTENTFUL_MANAGEMENT_TOKEN;

5. Створення файлу Excel для витягування інформації

Створіть файл Excel у шляху src/assets/document.xlsx. Це буде файл, з якого буде витягуватися інформація для завантаження в Contentful.
Переконайтеся, що структура Excel відповідає моделі контенту в Contentful.
У цьому випадку буде використовуватися модель “Contenido Transversal” (Трансконтентний контент), яка включає такі поля, як ім'я, код, заголовок, підзаголовок і опис.

6. Витягування інформації з файлу Excel

Потім створіть файл у шляху src/utils/ під назвою read-sheet-excel.js.
Імпортуйте бібліотеку xlsx, яку ви раніше встановили, і використовуйте методи readFile і utils.
Оголосіть функцію під назвою readSheetExcel, яка буде приймати як параметри шлях до файлу та номер листа Excel.
Ця функція буде читати файл, витягувати інформацію з вказаного листа і повертати JSON з отриманими даними.

import xlsxPkg from "xlsx";  
const { readFile, utils } = xlsxPkg;  

export const readSheetExcel = (filePath, sheet = 0) => {  
 const file = readFile(filePath);  
 const sheetName = file.SheetNames[sheet];  
 const worksheet = file.Sheets[sheetName];  

 return utils.sheet_to_json(worksheet);  
};

Далі, давайте викликаємо функцію, яку ми щойно створили, в файлі index.js. Для цього спочатку визначте функцію main у цьому файлі.
Усередині функції main виклич функцію readSheetExcel, передаючи як параметр шлях до файлу Excel, який містить інформацію, наприклад: ./src/assets/document.xlsx.

async function main() {  
 const info = readSheetExcel('./src/assets/document.xlsx');  
}  

main();

Після виконання цього кроку, інформація з файлу Excel буде перетворена у формат JSON, добре структурована і готова до використання для завантаження даних у Contentful.

7. Доступ до робочого простору та середовища

З наступною конфігурацією ви зможете отримати доступ до інформації вашого середовища та робочого простору.

const client = createClient({  
 accessToken: accessTokenCMA,  
 });  

 const space = await client.getSpace(spaceId);  
 const environment = await space.getEnvironment(envId);

8. Створення продуктів у Contentful на основі інформації з Excel

Далі ми використаємо отриманий JSON з файлу Excel для створення продуктів у Contentful.
Для цього виконай наступні кроки:

Перебери список продуктів:
Цикл for (const product of info) відповідає за ітерацію по масиву об'єктів під назвою info. Кожен об'єкт цього масиву представляє продукт з такою інформацією, як ім'я, код, заголовок, підзаголовок і опис.
Створи новий запис у Contentful:
Для кожного продукту використовується метод environment.createEntry для створення запису в моделі, яка називається contenidoTransversal. Тут призначаються значення кожного продукту до полів моделі:

name, code, title і subtitle заповнюються відповідними даними кожного продукту (наприклад, product.Nombre, product.Codigo і так далі).
textoEnriquecido — це поле, яке очікує структурований текст, що є поширеним форматом у Contentful. У цьому випадку в опис продукту включається текст з розширеним форматуванням.
Це організовано як вузол документа, що містить абзац з простим текстом.

Опублікуй запис:
Після того, як запис створено в середовищі Contentful, метод entry.publish() автоматично публікує його, роблячи його видимим у системі.
Підтвердження створення в консолі:
Після публікації кожного продукту, код виводить повідомлення в консоль за допомогою console.log(‘Продукт створено! ✅’), щоб вказати, що процес пройшов успішно.

//Створення продуктів у Contentful на основі інформації з Excel  
 for (const product of info) {  
 const entry = await environment.createEntry('contenidoTransversal', { fields: {  
 name: {'en-US': product.Nombre},  
 code: {'en-US': product.Codigo},  
 title: {'en-US': product.Titulo},  
 subtitle: {'en-US': product.Subtitulo},  
 textoEnriquecido: {  
 "en-US": {  
 data: {},  
 content: [  
 {  
 data: {},  
 content: [  
 {  
 data: {},  
 marks: [],  
 value: product.Descripcion,  
 nodeType: "text"  
 }  
 ],  
 nodeType: "paragraph"  
 }  
 ],  
 nodeType: "document"  
 }  
 },  

 }});  
 await entry.publish();  
 console.log('Продукт створено! ✅')  
 }

Важливо переконатися, що ти знаєш мову або locale, з якою налаштоване твоє середовище в Contentful.
У цьому випадку приклад використовує англійську мову США (en-US). Якщо ти не впевнений у locale, налаштованому в твоєму просторі, ти можеш перевірити це, увійшовши в розділ налаштувань Contentful і натиснувши на Locales.

Там ти знайдеш список мов, доступних у твоєму просторі.

Тепер, якщо ти виконаєш проект за допомогою наступної команди, вся інформація буде завантажена в твій простір Contentful.

node index.js

9. Отримання записів з Contentful

Як тільки продукти будуть завантажені, ми готові маніпулювати інформацією з Contentful.
У цій другій частині вправи ми будемо здійснювати масове оновлення поля name продуктів, додаючи до кожного з них персоналізований префікс.
За допомогою environment.getEntries виконується запит для отримання 5 раніше створених продуктів, які належать до типу контенту contenidoTransversal. Результат зберігається в змінній entries, яка містить список елементів під властивістю items.

//Отримати продукти, створені в Contentful  
let entries = await environment.getEntries({  
  content_type: "contenidoTransversal",  
  limit: 5,  
});

10. Оновлення та публікація

Ітерація через отримані записи:
За допомогою циклу for пройдемо через кожен продукт у entries.items. Для кожного:

Отримуємо повний запис за допомогою environment.getEntry(data.sys.id), використовуючи унікальний ID кожного продукту (data.sys.id).
2.
Отримуємо поточну назву продукту з entry.fields.name[“en-US”].

Оновлюємо назву продукту:
Скрипт додає префікс “Contentful > “ до поточної назви продукту і присвоює її в запис за допомогою: entry.fields.name = { “en-US”: newName }; Це замінює оригінальну назву на нову.
Зберігаємо та публікуємо зміни:

Метод entry.update() оновлює запис у Contentful, але не публікує його негайно.
2.
За допомогою nameUpdated.publish(), змінений запис публікується, і зміни набирають чинності.

Підтвердження зміни в консолі:
Після оновлення та публікації кожного продукту, виводиться повідомлення в консоль за допомогою console.log(‘Продукт створено! 🚀’).
Завершення процесу:
Після обробки всіх записів виводиться повідомлення "Процес завершено! ✨", щоб вказати, що скрипт завершив своє виконання.

//Оновити назву продуктів  
 for (let data of entries.items) {  
 let entry = await environment.getEntry(data.sys.id);   
 const newName = "Contentful > " + entry.fields.name["en-US"];  

 entry.fields.name = {  
 "en-US": newName,  
 };   
 const nameUpdated = await entry.update();  
 await nameUpdated.publish();  
 console.log('Продукт створено! 🚀')  
 }  

 console.log('Процес завершено! ✨');

Остаточний результат

- Наприкінці, ви можете виконати скрипт і перевірити результати.

node index.js
```

Як видно, всі назви продуктів були оновлені, додавши встановлений префікс.

Таким чином, ми змогли масово завантажити інформацію в Contentful з файлу Excel і швидко та ефективно оновити її, продемонструвавши потужність автоматизації за допомогою Content Management API (CMA).

12.

Повний код

Файл read-sheet-excel.js

import xlsxPkg from "xlsx";  
const { readFile, utils } = xlsxPkg;  

export const readSheetExcel = (filePath, sheet = 0) => {  
 const file = readFile(filePath);  
 const sheetName = file.SheetNames[sheet];  
 const worksheet = file.Sheets[sheetName];  

 return utils.sheet_to_json(worksheet);  
};

Файл index.js

import dotenv from "dotenv";  
dotenv.config({ path: ".env" });  

import contentfulPkg from "contentful-management";  
import { readSheetExcel } from "./src/utils/read-sheet-excel.js";  
const { createClient } = contentfulPkg;  

const spaceId = process.env.CONTENTFUL_SPACE_ID;  
const envId = process.env.CONTENTFUL_ENVIRONMENT;  
const accessTokenCMA = process.env.CONTENTFUL_MANAGEMENT_TOKEN;  

async function main() {  

 const info = readSheetExcel('./src/assets/document.xlsx');  

 const client = createClient({  
 accessToken: accessTokenCMA,  
 });  

 const space = await client.getSpace(spaceId);  
 const environment = await space.getEnvironment(envId);  

 //Створення продуктів в Contentful на основі даних з Excel  
 for (const product of info) {  
 const entry = await environment.createEntry('contenidoTransversal', { fields: {  
 name: {'en-US': product.Nombre},  
 code: {'en-US': product.Codigo},  
 title: {'en-US': product.Titulo},  
 subtitle: {'en-US': product.Subtitulo},  
 textoEnriquecido: {  
 "en-US": {  
 data: {},  
 content: [  
 {  
 data: {},  
 content: [  
 {  
 data: {},  
 marks: [],  
 value: product.Descripcion,  
 nodeType: "text"  
 }  
 ],  
 nodeType: "paragraph"  
 }  
 ],  
 nodeType: "document"  
 }  
 },  

 }});  
 await entry.publish();  
 console.log('Продукт створено! ✅')  
 }  

 //Отримання створених продуктів з Contentful  
 let entries = await environment.getEntries({  
 content_type: "contenidoTransversal",  
 limit: 5,  
 });  

 //Оновлення імені продуктів  
 for (let data of entries.items) {  
 let entry = await environment.getEntry(data.sys.id);   
 const newName = "Contentful > " + entry.fields.name["en-US"];  

 entry.fields.name = {  
 "en-US": newName,  
 };   
 const nameUpdated = await entry.update();  
 await nameUpdated.publish();  
 console.log('Продукт створено! 🚀')  
 }  

 console.log('Процес завершено! ✨');  
}  

main();

Висновки

Content Management API (CMA) від Contentful — це потужний інструмент для автоматизації та оптимізації управління контентом, що дозволяє масове завантаження, синхронізацію з зовнішніми системами та оновлення партій даних безпечно і масштабовано.
Її гнучкість та легкість інтеграції роблять її ідеальною для складних проєктів.

Дослідження додаткових вправ з CMA відкриває безліч можливостей для персоналізації робочих процесів, автоматизації повторюваних задач і більш ефективного управління контентом. Спробуй і підніми управління контентом на новий рівень!

Перекладено з: Contentful Content Management API (CMA): Carga y Actualización Masiva de Contenido