Перейти до вмісту
Blackbird API

Contentful

View on Github

Contentful — це безголова CMS, яка дозволяє компаніям створювати, керувати та доставляти цифровий контент на різних платформах і пристроях. Вона використовується переважно для ефективної організації та розповсюдження контенту, пропонуючи такі функції, як моделювання контенту, версіонування та доставка контенту на основі API.

Перед налаштуванням

Перед тим, як підключитися, переконайтеся, що:

  • У вас є акаунт Contentful з простором, до якого ви хочете підключитися.
  • Ваш акаунт Contentful має відповідні дозволи в просторі. Ви можете дізнатися більше про ролі та дозволи просторів тут.
  • Ви створили власний OAuth додаток.

Створення OAuth додатку

  1. Перейдіть на сторінку OAuth applications і натисніть New Application.
  2. Введіть Name та Description додатку. У полі Redirect URI вкажіть https://bridge.blackbird.io/api/ImplicitGrant. Це URL-адреса, куди Blackbird отримає код авторизації.
  3. Під Redirect URI виберіть Content management manage.
  4. Натисніть Create Application.
  5. Після створення додатку буде згенеровано Client ID. Client ID потрібен для підключення до Contentful через Blackbird.

Підключення

  1. Перейдіть до додатків і знайдіть Contentful.
  2. Натисніть Add Connection.
  3. Назвіть ваше підключення для подальшого використання, наприклад, ‘Мій клієнт’.
  4. Заповніть поле Client ID, отримане раніше.
  5. Заповніть поле Space ID простору Contentful, до якого ви хочете підключитися. Щоб знайти ID простору, дотримуйтесь цих інструкцій.
  6. Base URL: за замовчуванням встановлено URL https://api.contentful.com. Якщо ви працюєте в ЄС, вам слід змінити це на https://api.eu.contentful.com.
  7. Натисніть Authorize connection.
  8. Дотримуйтесь інструкцій, які надає Contentful, авторизуючи Blackbird.io діяти від вашого імені.
  9. Після повернення до Blackbird переконайтеся, що з’явилося підключення і його статус - Connected.

connecting

Робота з перекладами

Дотримуйтесь цього посібника, щоб мати можливість працювати з перекладами в Contentful.

Actions

Entries

  • Get locales повертає локалі за замовчуванням та список інших локалей, усі в кодовій формі, що легко використовувати разом з оператором конвертації.
  • Get entry’s text/rich text field повертає вміст поля короткого тексту, довгого тексту або форматованого тексту запису як рядок.
  • Get text/rich text field as HTML file повертає вміст поля короткого тексту, довгого тексту або форматованого тексту запису як HTML-файл.
  • Set entry’s text/rich text field встановлює вміст поля короткого тексту, довгого тексту або форматованого тексту запису з рядка.
  • Set text/rich text field from HTML file встановлює вміст поля короткого тексту, довгого тексту або форматованого тексту запису з HTML-файлу. Для короткого/довгого тексту в поле вставляється лише текст, вилучений з файлу. Для форматованого тексту зберігається вся структура HTML.
  • Get entry’s number field повертає значення числового поля запису.
  • Set entry’s number field встановлює значення числового поля запису.
  • Get entry’s boolean field повертає значення логічного поля запису.
  • Set entry’s boolean field встановлює значення логічного поля запису.
  • Get entry’s media content повертає ідентифікатор ресурсу, прикріпленого до медіа-поля запису.
  • Set entry’s media field встановлює медіа-поле запису із вказаним ресурсом.
  • Search entries повертає список записів. Опціонально можна фільтрувати за моделлю контенту, середовищем, тегами та датою останнього оновлення.
  • Get entry отримати деталі конкретного запису.
  • Add new entry створює новий запис із вказаною моделлю контенту.
  • Find entry by field value враховуючи поле та бажане значення для поля, буде повернуто перший відповідний запис.
  • Delete entry.
  • Publish entry.
  • Unpublish entry.
  • List missing locales for a field повертає список відсутніх перекладів для вказаного поля.
  • List missing locales for entry повертає список відсутніх перекладів для вказаного запису.
  • Get entry as HTML file повертає всі локалізовані поля вказаного запису як HTML-файл (дивіться більше інформації нижче).
  • Update entry from HTML file оновлює всі локалізовані поля вказаного запису.

Get entry as HTML file і Update entry from HTML file призначені для використання разом у типовому процесі перекладу: ви можете отримати локалізовані поля запису як HTML-файл, відправити його до TMS, потім отримати перекладений HTML-файл і повернути його в запис Contentful. Update entry from HTML file очікує таку ж структуру HTML, як і структура файлу, отриманого за допомогою Get entry as HTML file.

Важливе зауваження: переконайтеся, що ваш запис має поля з увімкненою локалізацією. Ви повинні явно встановити цю властивість для кожного поля (див. зображення нижче).

1707747998688 1707748006274

Дія Get entry as HTML file також дозволяє визначити, чи хочете ви рекурсивно вбудовувати вміст (для перекладу) з пов’язаних записів.

Існує 4 типи пов’язаних записів:

  • Типи полів посилань з моделі контенту
  • Гіперпосилання, які посилаються на запис у полях ‘Rich text’
  • Вбудовані вбудовані записи в полях ‘Rich text’
  • Блокові вбудовані записи в полях ‘Rich text’

У цій дії ви можете вибрати, який саме тип пов’язаного запису ви хочете включити в експортований HTML-файл. Якщо ви, наприклад, вибираєте ‘Hyperlinks’ та ‘Inline embedded entries’, ми рекурсивно переглянемо всі поля ‘Rich text’ і отримаємо весь вміст цих вбудованих записів. Для цих вбудованих записів ми робимо те ж саме і також отримуємо всі гіперпосилання та вбудовані вбудовані записи, і так далі.

Примітка: ви також можете вказати, чи хочете ви ігнорувати аспект локалізації для полів посилань. Якщо це необов’язкове введення встановлено як true, і ‘Include referenced entries’ також true, тоді всі пов’язані записи будуть включені незалежно від налаштування локалізації.

Нарешті, ви можете вказати список ID полів, які завжди будуть ігноруватися і не додаватимуться до створеного HTML-файлу.

Для отримання додаткової інформації про локалізацію CMS перегляньте цей посібник.

Assets

  • Get asset повертає заголовок, опис та файл, прикріплений до ресурсу.
  • Create and upload asset.
  • Update asset file.
  • Delete asset видалити вказаний ресурс.
  • Publish asset.
  • Unpublish asset.
  • Is asset locale present перевіряє, чи присутній вказаний переклад файлу для ресурсу.
  • List missing locales for an asset повертає список усіх відсутніх перекладів для ресурсу.
  • Add asset tag додати новий тег до вказаного ресурсу.
  • Remove asset tag видалити конкретний тег з ресурсу.

Content models

  • List all content models повертає всі моделі контенту, доступні в просторі.
  • Get content model отримати деталі конкретної моделі контенту.

Tag

  • List tags список усіх тегів контенту в просторі.
  • Create tag створити новий тег контенту.
  • Get tag отримати деталі конкретного тегу.
  • Delete tag видалити конкретний тег контенту.
  • Add tag to entry додати конкретний тег до запису.
  • Remove tag from entry видалити конкретний тег із запису.

Content types

  • List all content types повертає всі типи контенту, доступні в просторі.

Entry tasks

  • Search entry tasks повертає список завдань на основі вказаних фільтрів.
  • Get entry task повертає деталі конкретного завдання.
  • Update entry task оновлює завдання запису новими деталями.

Зауважте, щоб використовувати дії Entry tasks, вам потрібно встановити додаток Workflows (розроблений Contentful) у вашому просторі Contentful.

Workflows

  • Get workflow повертає деталі конкретного робочого процесу на основі ID робочого процесу.
  • Get workflow definition повертає деталі конкретного визначення робочого процесу на основі ID визначення робочого процесу.
  • Update workflow step переміщує робочий процес на конкретний крок.
  • Complete workflow завершує робочий процес.
  • Cancel workflow скасовує робочий процес.

Events

  • On entry published і On asset published є найбільш корисними подіями. Вони спрацьовують, коли будь-який запис/ресурс публікується, і можуть бути ідеальним тригером для відправлення запису/ресурсу на переклад на основі відсутніх перекладів (див. приклад). За бажанням ви також можете фільтрувати ці події за тегами. Якщо ви це зробите, подія буде спрацьовувати, лише якщо всі теги, які ви ввели, присутні в записі.
  • On entry task created і On entry task saved корисні, якщо ви вважаєте за краще працювати з розширенням ‘Workflows’ для Blackbird. Ви можете використовувати розширення для призначення запису до робочого процесу, створюючи завдання. Ці події навіть можуть фільтрувати на основі призначеного ID користувача та опису завдання. Дивіться приклад нижче.
  • On workflow updated спрацьовує, коли робочий процес оновлюється або створюється. Також спрацьовує, коли робочий процес змінює свій крок.
  • On workflow completed спрацьовує, коли робочий процес завершується.

Інші події:

  • On entry created
  • On entry saved
  • On entry auto saved
  • On entry unpublished
  • On entry archived
  • On entry unarchived
  • On entry deleted
  • On asset created
  • On asset saved
  • On asset auto saved
  • On asset unpublished
  • On asset archived
  • On asset unarchived
  • On asset deleted

Приклади

example

У цьому прикладі, коли запис публікується, ми отримуємо локалізовані поля як HTML-файл і отримуємо відсутні переклади. Потім ми створюємо новий проект Phrase з відсутніми локалями як цільовими мовами та створюємо нове завдання Phrase для файлу.

example2

У цьому прикладі, коли запис публікується, ми отримуємо всі локалізовані поля як HTML-файл. Потім ми надсилаємо файл на DeepL для перекладу і миттєво