npm package: @nikolaymatrosov/n8n-nodes-yc
Description: n8n nodes for Yandex Cloud services
Author: Nikolay Matrosov
Latest version: 0.13.0

# Описание нод пакета n8n-nodes-yc

Пакет интеграций для работы с сервисами Yandex Cloud в n8n.

## Содержание

1. [Yandex Cloud GPT Chat Model](#yandex-cloud-gpt-chat-model)
2. [Yandex Cloud Foundation Models](#yandex-cloud-foundation-models)
3. [Yandex Object Storage](#yandex-object-storage)
4. [Yandex Cloud Functions](#yandex-cloud-functions)
5. [Yandex Cloud Containers](#yandex-cloud-containers)
6. [Yandex Cloud Compute](#yandex-cloud-compute)
7. [Yandex Cloud Data Streams](#yandex-cloud-data-streams)
8. [Yandex Cloud Message Queue](#yandex-cloud-message-queue)
9. [Yandex Cloud Postbox](#yandex-cloud-postbox)
10. [Yandex Cloud SpeechKit](#yandex-cloud-speechkit)
11. [Yandex Cloud SpeechKit STT](#yandex-cloud-speechkit-stt)
12. [Yandex Cloud Translate](#yandex-cloud-translate)
13. [Yandex Cloud Workflows](#yandex-cloud-workflows)
14. [Yandex Cloud YDB](#yandex-cloud-ydb)
15. [Yandex Cloud Search](#yandex-cloud-search)
16. [Yandex Cloud Vision OCR](#yandex-cloud-vision-ocr)
17. [Yandex Cloud Logging](#yandex-cloud-logging)
18. [Yandex Cloud YandexART](#yandex-cloud-yandexart)
19. [Yandex Cloud Lockbox](#yandex-cloud-lockbox)

---

## Yandex Cloud GPT Chat Model

**Нода для интеграции с Yandex Cloud Foundation Models API в качестве языковой модели для LangChain.** Эта нода является компонентом AI-цепочек и представляет собой Chat Model, совместимую с фреймворком LangChain. Предназначена для продвинутого использования в AI-агентах и цепочках обработки (AI Chain, AI Agent). Нода не имеет входов и выводит объект языковой модели, который можно подключать к другим AI-компонентам n8n.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Model** | Resource Locator | ID модели YandexGPT (например, `yandexgpt/latest`) |
| **Maximum Tokens** | Number | Максимальное количество токенов в ответе (до 8000) |
| **Temperature** | Number | Контроль случайности генерации (0-1, по умолчанию 0.6) |
| **Timeout** | Number | Таймаут запроса в миллисекундах (по умолчанию 60000) |
| **Max Retries** | Number | Максимальное количество повторных попыток (по умолчанию 2) |

**Аутентификация:** Использует API ключ через credentials `yandexCloudGptApi` с передачей folder ID в заголовке `x-folder-id`. Поддерживает настройку базового URL API. Нода совместима с OpenAI API протоколом, что позволяет использовать стандартные LangChain инструменты. Идеально подходит для создания чат-ботов, RAG-систем и AI-агентов с использованием российских языковых моделей.

---

## Yandex Cloud Foundation Models

**Нода для работы с Foundation Models API Yandex Cloud, предоставляющая прямой доступ к генеративным языковым моделям YandexGPT через REST API.** В отличие от Chat Model версии, эта нода работает как обычная трансформационная нода с входами и выходами Main-типа, позволяя отправлять запросы к API и получать JSON-ответы в контексте стандартного workflow.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Тип ресурса (Chat) |
| **Operation** | Options | Операция для выполнения |

**Ресурсы и операции:**

- **Chat** - работа с чат-функциональностью модели

**Аутентификация:** Использует API ключ через credentials `yandexCloudFomoApi`. Поддерживает настройку базового URL и автоматическую обработку HTTP ошибок (ignoreHttpStatusErrors). Включает выбор модели из выпадающего списка (аналогично LMChatYandexGpt) и расширенные сообщения об ошибках с детальными ответами API. Нода подходит для простых сценариев генерации текста, где не требуется сложная интеграция с LangChain, но нужна прямая работа с API Yandex Cloud для создания диалогов, генерации контента и обработки естественного языка в автоматизированных процессах.

---

## Yandex Object Storage

**Нода для полноценного управления объектным хранилищем Yandex Cloud, совместимым с Amazon S3 API.** Предоставляет исчерпывающий набор операций для работы как с bucket'ами (контейнерами), так и с объектами (файлами), используя AWS SDK для обеспечения максимальной совместимости и надежности.

| Параметр | Тип | Ресурсы | Операции |
|----------|-----|---------|----------|
| **Bucket** | Resource | Bucket | Create, Delete, Get, List, Set ACL, Set Versioning |
| **Object** | Resource | Object | Upload, Download, Copy, Move, Delete, Get, List, Set ACL, Get Presigned URL |

**Операции с Bucket:**

- **Create** - создание нового bucket с настройкой ACL
- **Delete** - удаление пустого bucket
- **Get** - получение информации о bucket (location, metadata)
- **List** - перечисление всех доступных bucket'ов
- **Set ACL** - настройка прав доступа (private, public-read, public-read-write, authenticated-read)
- **Set Versioning** - включение/отключение версионирования объектов

**Операции с Object:**

- **Upload** - загрузка из бинарных данных, текста или JSON с настройкой content-type, storage class (Standard/Cold/Ice) и метаданных. Возвращает поле `objectUrl` с полным URL объекта (например, `https://storage.yandexcloud.net/my-bucket/file.txt`)
- **Download** - скачивание объекта в бинарный формат
- **Copy** - копирование между bucket'ами с сохранением метаданных. Возвращает поле `objectUrl` с URL объекта назначения
- **Move** - перемещение с автоматическим удалением источника. Возвращает поле `objectUrl` с URL объекта назначения
- **Delete** - удаление объекта
- **Get** - получение метаданных (size, content-type, ETag, версия)
- **List** - перечисление объектов с фильтрацией по префиксу и пагинацией (до 1000 объектов)
- **Set ACL** - настройка прав доступа на уровне объекта
- **Get Presigned URL** - генерация временных подписанных URL для безопасного доступа

**Аутентификация:** Использует статические ключи доступа (access key ID и secret access key) через credentials `yandexCloudStaticApi`. Поддерживает resource locator для удобного выбора bucket'ов из списка или ввода имени вручную. Нода идеально подходит для резервного копирования, хранения файлов пользователей, CDN-интеграций и организации data lake в облаке.

---

## Yandex Cloud Functions

**Нода для вызова serverless-функций в Yandex Cloud Functions через HTTP-эндпоинты.** Позволяет запускать облачные функции с передачей параметров и получением результатов выполнения, автоматически управляя аутентификацией через IAM-токены.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Folder ID** | String | ID папки для поиска функций (по умолчанию из credentials) |
| **Function** | Options | Выбор функции из списка или указание ID |
| **HTTP Method** | Options | GET или POST |
| **Request Body** | String (JSON) | Тело запроса для POST-метода |
| **Query Parameters** | Collection | Коллекция query-параметров (name/value) |
| **Headers** | Collection | Дополнительные HTTP-заголовки |

**Процесс выполнения:**

1. Автоматическая загрузка списка доступных функций из указанной папки через SDK
2. Получение IAM-токена из service account credentials
3. Формирование HTTP-запроса к эндпоинту `https://functions.yandexcloud.net/{functionId}`
4. Добавление заголовка Authorization с Bearer-токеном
5. Выполнение запроса и парсинг ответа (автоматическое определение JSON)

**Возвращаемые данные:**

- `statusCode` - HTTP статус ответа
- `headers` - заголовки ответа
- `body` - тело ответа (объект или строка)

**Аутентификация:** Использует service account JSON через credentials `yandexCloudAuthorizedApi` для автоматического получения IAM-токенов. Валидирует JSON-тело запроса перед отправкой. Нода идеально подходит для интеграции бизнес-логики, написанной на Python, Node.js, Go и других языках, в n8n workflows, обеспечивая возможность выполнения сложных вычислений и обработки данных в serverless-архитектуре.

---

## Yandex Cloud Containers

**Нода для вызова serverless-контейнеров в Yandex Cloud Serverless Containers, предоставляющая возможность запуска контейнеризированных приложений через HTTP.** Функционал аналогичен Yandex Cloud Functions, но работает с Docker-контейнерами, что позволяет использовать любые зависимости и окружения.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Folder ID** | String | ID папки для поиска контейнеров |
| **Container** | Options | Выбор контейнера из списка или указание ID |
| **HTTP Method** | Options | GET или POST |
| **Request Body** | String (JSON) | Тело запроса для POST-метода |
| **Query Parameters** | Collection | URL-параметры запроса |
| **Headers** | Collection | Пользовательские HTTP-заголовки |

**Процесс работы:**

1. Загрузка списка доступных контейнеров через SDK
2. Получение URL контейнера (поле `url`)
3. Генерация IAM-токена для аутентификации
4. Выполнение HTTP-запроса к URL контейнера
5. Обработка и возврат ответа

**Возвращаемые данные:**

- `statusCode` - HTTP код ответа
- `headers` - заголовки ответа
- `body` - тело ответа (автоматический парсинг JSON)

**Аутентификация:** Service account JSON с автоматическим получением IAM-токенов через `yandexCloudAuthorizedApi`. Поддерживает валидацию JSON перед отправкой. Отличается от Functions тем, что использует полные Docker-образы, что дает больше гибкости в выборе runtime, библиотек и системных зависимостей. Подходит для запуска ML-моделей, сложных приложений с множеством зависимостей и микросервисов в рамках n8n workflows.

---

## Yandex Cloud Compute

**Нода для управления виртуальными машинами в Yandex Compute Cloud, предоставляющая базовые операции запуска и остановки инстансов.** Использует официальный Yandex Cloud SDK для взаимодействия с Compute API.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Тип ресурса (Instance) |
| **Operation** | Options | Start или Stop |
| **Folder ID** | String | ID папки с виртуальными машинами |
| **Instance** | Options | Выбор VM из списка или указание ID |

**Операции:**

- **Start** - запуск остановленной виртуальной машины
- **Stop** - остановка работающей виртуальной машины

**Процесс выполнения:**

1. Парсинг service account JSON credentials
2. Создание SDK сессии с аутентификацией
3. Получение списка инстансов из указанной папки
4. Выполнение операции start/stop через InstanceServiceClient
5. Возврат информации об операции

**Возвращаемые данные:**

- `success` - статус выполнения
- `operation` - тип операции (start/stop)
- `instanceId` - ID виртуальной машины
- `operationId` - ID операции в Yandex Cloud
- `done` - завершена ли операция
- `metadata` - метаданные операции

**Аутентификация:** Service account JSON через `yandexCloudAuthorizedApi` с валидацией обязательных полей (serviceAccountId, accessKeyId, privateKey). Нода показывает статус VM при выборе из списка (RUNNING, STOPPED и т.д.). Идеально подходит для автоматизации управления инфраструктурой: запуск VM по расписанию, остановка для экономии средств, интеграция с мониторингом и системами оповещения.

---

## Yandex Cloud Data Streams

**Нода для работы с потоковой обработкой данных через Yandex Cloud Data Streams (YDS), совместимый с Apache Kafka и Amazon Kinesis API.** Обеспечивает высокопроизводительную передачу данных между приложениями с гарантией доставки и порядка сообщений.

| Параметр | Тип | Ресурсы | Операции |
|----------|-----|---------|----------|
| **Record** | Resource | Record | Put, Put Multiple |
| **Stream** | Resource | Stream | Describe, List |

**Операции с Record:**

- **Put** - отправка одной записи с выбором типа данных (String/JSON), указанием partition key и опциональных параметров (explicit hash key, sequence number)
- **Put Multiple** - пакетная отправка записей в двух режимах:
  - **Define Records** - ручное определение записей через UI
  - **Use Input Data** - автоматическое использование входящих элементов с маппингом полей

**Операции со Stream:**

- **Describe** - получение детальной информации о потоке (статус, retention period, shards, encryption)
- **List** - перечисление всех доступных потоков с лимитом

**Параметры отправки:**

- `streamName` - имя потока (формат: `/ru-central1/{folder-id}/{database-id}/{stream-name}`)
- `data` - данные для отправки (строка или JSON)
- `partitionKey` - ключ для определения shard'а
- `explicitHashKey` - явное указание hash для routing
- `dataField` - поле с данными при использовании input data
- `partitionKeyField` - поле с partition key

**Возвращаемые данные:**

- Для Put: `shardId`, `sequenceNumber`, `encryptionType`
- Для Put Multiple: `successCount`, `failedCount`, детальная информация по каждой записи
- Для Describe: полная информация о потоке, shards с hash ranges
- Для List: список имен потоков

**Аутентификация:** Статические ключи через `yandexCloudStaticApi`, использует Kinesis-совместимый endpoint. Поддерживает resource locator для удобного выбора потоков. Нода подходит для построения real-time аналитики, потоковой ETL-обработки, сбора логов и метрик, интеграции микросервисов с гарантией доставки сообщений и возможностью горизонтального масштабирования через sharding.

---

## Yandex Cloud Message Queue

**Нода для отправки сообщений в очереди Yandex Cloud Message Queue (YMQ), полностью совместимые с Amazon SQS API.** Предоставляет надежную асинхронную передачу сообщений между компонентами распределенных систем с поддержкой FIFO и стандартных очередей.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Message |
| **Operation** | Options | Send |
| **Queue** | Resource Locator | Выбор очереди из списка или указание URL |
| **Message Body** | String | Содержимое сообщения (до 256 KB) |

**Дополнительные поля:**

- **Delay Seconds** - задержка доставки сообщения (0-900 секунд)
- **Message Deduplication ID** - токен для дедупликации (обязателен для FIFO)
- **Message Group ID** - группировка сообщений (обязателен для FIFO)

**Message Attributes:**
Коллекция атрибутов сообщения с настройкой:

- `name` - имя атрибута
- `dataType` - тип данных (String, Number, Binary)
- `value` - значение атрибута

**Возвращаемые данные:**

- `messageId` - уникальный ID сообщения
- `md5OfMessageBody` - MD5 хеш тела сообщения
- `md5OfMessageAttributes` - MD5 хеш атрибутов
- `sequenceNumber` - порядковый номер (для FIFO)
- `success` - статус отправки
- `queueUrl` - URL очереди

**Аутентификация:** Статические ключи через `yandexCloudStaticApi`, использует endpoint `https://message-queue.api.cloud.yandex.net`. Поддерживает как стандартные очереди (at-least-once delivery, best-effort ordering), так и FIFO-очереди (exactly-once processing, strict ordering). Нода идеально подходит для построения event-driven архитектур, разделения монолитов на микросервисы, буферизации нагрузки между компонентами, обработки фоновых задач и обеспечения отказоустойчивости через асинхронную коммуникацию.

---

## Yandex Cloud Postbox

**Нода для отправки транзакционных email через Yandex Cloud Postbox, использующий Amazon SES v2 API.** Предоставляет надежную доставку писем с поддержкой HTML-шаблонов и переменных, с гарантированной репутацией IP-адресов Yandex Cloud.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Email |
| **Operation** | Options | Send |
| **Email Type** | Options | Simple или Template |
| **From Email** | String | Email отправителя (домен должен быть верифицирован) |
| **To Email** | String | Email получателя (можно несколько через запятую) |

**Simple Email (простой режим):**

- **Subject** - тема письма
- **HTML Body** - HTML-версия письма
- **Text Body** - текстовая версия для клиентов без HTML

**Template Email (шаблонный режим):**

- **Template Subject** - тема с переменными `{{variable}}`
- **Template HTML** - HTML-шаблон с плейсхолдерами
- **Template Text** - текстовая версия шаблона (опционально)
- **Template Data** - JSON-объект с данными для подстановки

**Процесс отправки:**

1. Парсинг списка получателей (разделение по запятой)
2. Формирование структуры Content (Simple или Template)
3. Подстановка переменных в шаблон (если используется)
4. Отправка через SES API с charset UTF-8
5. Получение Message ID

**Возвращаемые данные:**

- `messageId` - уникальный ID отправленного письма
- `success` - статус отправки
- `from` - адрес отправителя
- `to` - массив адресов получателей
- `subject` - тема письма
- `emailType` - тип письма (simple/template)

**Аутентификация:** Статические ключи через `yandexCloudStaticApi`, использует endpoint `https://postbox.cloud.yandex.net`. Требует предварительной верификации домена в Yandex Cloud. Поддерживает множественных получателей и шаблонизацию для персонализации. Нода подходит для отправки уведомлений, подтверждений регистрации, сброса паролей, отчетов, маркетинговых рассылок и любых транзакционных email с высокой доставляемостью и детальной аналитикой.

---

## Yandex Cloud SpeechKit

**Нода для синтеза речи (Text-to-Speech) с использованием Yandex SpeechKit API v3, предоставляющая высококачественную генерацию аудио из текста.** Поддерживает множество голосов, эмоциональные роли и гибкую настройку параметров синтеза.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Speech |
| **Operation** | Options | Synthesize |
| **Text** | String | Текст для синтеза (многострочный) |
| **Voice** | Options | Выбор голоса (Alena, Filipp, Jane, John, Masha, Omazh, Zahar) |
| **Role** | Options | Эмоциональная окраска (Neutral, Good, Evil) |

**Доступные голоса:**

- **Alena** - женский, русский
- **Filipp** - мужской, русский
- **Jane** - женский, русский/английский
- **John** - мужской, английский
- **Masha** - женский, русский
- **Omazh** - женский, русский
- **Zahar** - мужской, русский

**Форматы аудио:**

*Container (файлы в контейнере):*

- **WAV** - несжатый формат
- **MP3** - сжатый с потерями
- **OGG Opus** - открытый кодек

*Raw PCM (сырой аудиопоток):*

- Частоты дискретизации: 8000, 16000, 22050, 48000 Hz
- Кодировка: LINEAR16_PCM

**Дополнительные опции:**

- **Speed** - скорость речи (0.1 - 3.0, по умолчанию 1.0)
- **Volume** - громкость (-145 до 1)
- **Pitch Shift** - изменение тона голоса (-1000 до 1000 Hz)

**Процесс синтеза:**

1. Парсинг service account credentials
2. Создание SDK сессии
3. Подключение к TTS API (`tts.api.cloud.yandex.net:443`)
4. Потоковая генерация аудио chunks
5. Объединение chunks в итоговый файл
6. Подготовка бинарных данных с правильным MIME-типом

**Возвращаемые данные:**

- `success` - статус синтеза
- `text` - исходный текст
- `voice` - использованный голос
- `role` - эмоциональная роль
- `audioFormat` - формат аудио
- `audioSize` - размер файла в байтах
- Binary data - аудиофайл с расширением .wav/.mp3/.ogg/.raw

**Аутентификация:** Service account JSON через `yandexCloudAuthorizedApi` с автоматической генерацией IAM-токенов. Использует gRPC streaming для эффективной передачи аудио. Нода идеально подходит для создания голосовых помощников, озвучивания уведомлений, генерации аудиокниг, accessibility-решений, IVR-систем и любых приложений, требующих преобразования текста в естественную речь на русском и английском языках.

---

## Yandex Cloud SpeechKit STT

**Нода для распознавания речи (Speech-to-Text) с использованием Yandex SpeechKit API v3, обеспечивающая асинхронную транскрибацию аудио с высокой точностью.** Поддерживает множество языков и аудиоформатов с возможностью автоматического определения языка.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Operation** | Options | Recognize Audio или Get Recognition Results |
| **Audio URL** | String | URL аудиофайла в Yandex Object Storage |
| **Language Code** | Options | Язык распознавания (авто-определение, русский, английский и др.) |
| **Format Specification** | Options | Выбор способа указания формата: коды Audio Format или MIME Types |
| **Audio Format** | Options | Формат аудио Yandex Cloud (LPCM, OGG Opus, MP3) - отображается при выборе "Audio Format" |
| **MIME Type** | Options | Стандартный MIME тип (audio/wav, audio/ogg, audio/mpeg и др.) - отображается при выборе "MIME Type" |

**Операции:**

- **Recognize Audio** - запуск асинхронной транскрибации аудио
  - Возвращает operation ID для опроса результатов
  - Поддерживает аудиофайлы в Yandex Object Storage
  
- **Get Recognition Results** - получение результатов транскрибации с авто-опросом
  - Автоматический опрос до завершения
  - Обработка race condition "operation not ready"
  - Настраиваемый интервал опроса и макс. попыток
  - Опциональные частичные результаты при таймауте

**Поддерживаемые языки:**

- Автоматическое определение
- Русский (ru-RU)
- Английский (en-US)
- Немецкий (de-DE)
- Французский (fr-FR)
- Испанский (es-ES)
- Итальянский (it-IT)
- Польский (pl-PL)
- Турецкий (tr-TR)
- И многие другие (всего 16 языков)

**Форматы аудио:**

Нода поддерживает два способа указания формата аудио:

*Через Audio Format (коды форматов Yandex Cloud):*

- **LPCM** - Linear PCM с настраиваемой частотой дискретизации (8000, 16000, 48000 Гц)
- **OGG Opus** - Сжатый формат Ogg Opus
- **MP3** - Стандартный формат MP3

*Через MIME Type (стандартные MIME типы, автоматически преобразуются в форматы Yandex):*

- **audio/wav, audio/pcm, audio/x-pcm** - Преобразуется в LPCM
- **audio/ogg, audio/opus** - Преобразуется в OGG Opus
- **audio/mpeg, audio/mp3** - Преобразуется в MP3

**Опции распознавания:**

- **Audio Channel Count** - количество аудиоканалов (1-8)
- **Sample Rate** - для формата LPCM (8000, 16000, 48000 Гц)
- **Profanity Filter** - фильтрация нецензурной лексики
- **Literature Text** - использование литературной нормализации текста

**Опции опроса (Get Results):**

- **Poll Interval** - время между попытками опроса (1-60 секунд, по умолчанию 5)
- **Max Attempts** - максимальное количество попыток опроса (1-300, по умолчанию 60)
- **Return Partial Results** - возврат неполных результатов при таймауте

**Процесс распознавания:**

1. Загрузка аудиофайла в Yandex Object Storage
2. Запуск распознавания с URL аудио и параметрами
3. Получение operation ID
4. Опрос результатов (авто-повтор при ошибках "not ready")
5. Получение распознанного текста с оценками достоверности

**Возвращаемые данные (Recognize):**

- `success` - статус запуска операции
- `operationId` - ID для опроса результатов
- `audioUrl` - URL аудиофайла
- `model` - использованная модель распознавания (general)
- `languageCode` - выбранный язык
- `status` - статус операции (RUNNING)

**Возвращаемые данные (Get Results):**

- `success` - статус завершения
- `operationId` - ID операции
- `status` - DONE или RUNNING
- `text` - полный распознанный текст
- `channelTag` - идентификатор аудиоканала
- `finalResults` - детальные результаты с альтернативами
- `attemptsUsed` - количество использованных попыток опроса

**Аутентификация:** Service account JSON через `yandexCloudAuthorizedApi` с автоматической генерацией IAM-токенов. Использует gRPC streaming для эффективной передачи данных. Автоматически обрабатывает race condition, когда данные операции не сразу доступны. Нода идеально подходит для создания голосовых интерфейсов, транскрибации встреч, аналитики call-центров, генерации субтитров, accessibility-функций и любых приложений, требующих точного преобразования речи в текст на множестве языков с поддержкой асинхронной обработки.

---

## Yandex Cloud Translate

**Нода для перевода текста с использованием Yandex Cloud Translate API, предоставляющая высококачественный нейронный машинный перевод для более чем 100 языков.** Поддерживает автоматическое определение языка, пользовательские глоссарии, перевод HTML и проверку орфографии перед переводом.

|| Параметр | Тип | Описание |
||----------|-----|----------|
|| **Resource** | Options | Text или Language |
|| **Operation** | Options | Translate, Detect Language или List |
|| **Folder ID** | String | ID папки (по умолчанию из credentials) |

**Ресурсы и операции:**

- **Text** - перевод текста и определение языка
  - **Translate** - перевод текста на целевой язык с опциональным глоссарием
  - **Detect Language** - автоматическое определение языка текста
- **Language** - управление поддерживаемыми языками
  - **List** - получение всех поддерживаемых языков

**Параметры перевода:**

- `texts` - текст для перевода (многострочный, поддерживает несколько текстов через перевод строки)
- `sourceLanguageCode` - исходный язык (оставьте пустым для автоопределения)
- `targetLanguageCode` - целевой язык (обязательный)
- `format` - формат текста (Plain Text или HTML)
- `speller` - включить проверку орфографии перед переводом
- `model` - ID пользовательской модели перевода (опционально)
- `glossary` - пользовательские термины глоссария для точного перевода

**Конфигурация глоссария:**

Словарь пользовательских терминов для точного перевода специфических терминов:

- `sourceText` - термин на исходном языке
- `translatedText` - термин на целевом языке
- `exact` - использовать точное совпадение слов

**Определение языка:**

- `text` - текст для определения языка
- `languageCodeHints` - коды языков через запятую для приоритизации (например, en,ru,es)

**Поддерживаемые языки:**

Более 100 языков, включая: русский, английский, немецкий, французский, испанский, итальянский, португальский, польский, турецкий, китайский, японский, корейский, арабский, иврит, хинди и многие другие. Полный список доступен через операцию List Languages.

**Ограничения API:**

- Максимум 10,000 символов на запрос
- Несколько текстов можно переводить в одном запросе
- Поддерживается пакетный перевод через ввод с разделением строками

**Возвращаемые данные (Translate):**

- `success` - статус перевода
- `sourceLanguageCode` - исходный язык (авто-определен, если не указан)
- `targetLanguageCode` - целевой язык
- `translations` - массив результатов перевода
  - `text` - переведенный текст
  - `detectedLanguageCode` - определенный исходный язык

**Возвращаемые данные (Detect Language):**

- `success` - статус определения
- `text` - анализируемый текст
- `languageCode` - определенный код языка

**Возвращаемые данные (List Languages):**

- Массив поддерживаемых языков с:
  - `code` - код языка (ISO 639-1)
  - `name` - название языка

**Сценарии использования:**

- Локализация многоязычного контента
- Перевод чата в реальном времени
- Рабочие процессы перевода документов
- Перевод пользовательского контента
- Поддержка клиентов на нескольких языках
- Локализация ответов API
- Перевод email и уведомлений
- Перевод содержимого веб-сайтов

**Аутентификация:** Service account JSON через `yandexCloudAuthorizedApi` с автоматической генерацией IAM-токенов. Использует Yandex Cloud Translate API v2 с gRPC протоколом для эффективной коммуникации. Нода идеально подходит для создания многоязычных приложений, автоматизации перевода контента, создания pipeline'ов перевода и интеграции машинного перевода в бизнес-процессы с поддержкой пользовательской терминологии и сохранением HTML-контента.

---

## Yandex Cloud Workflows

**Нода для запуска выполнения рабочих процессов в Yandex Cloud Workflows, serverless-сервисе для оркестрации облачных ресурсов и микросервисов.** Позволяет интегрировать n8n workflows с Yandex Workflows, создавая гибридные автоматизации.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Workflow |
| **Operation** | Options | Start Execution |
| **Folder ID** | String | ID папки с workflows |
| **Workflow** | Options | Выбор workflow из списка или указание ID |
| **Input Data** | String (JSON) | Входные данные для workflow в формате JSON |

**Процесс запуска:**

1. Загрузка списка доступных workflows из указанной папки
2. Валидация входных данных (проверка корректности JSON)
3. Создание SDK клиента ExecutionServiceClient
4. Отправка запроса на запуск выполнения с указанием:
   - `workflowId` - ID рабочего процесса
   - `input.inputJson` - JSON-строка с входными параметрами
5. Получение execution ID

**Возвращаемые данные:**

- `executionId` - уникальный ID запущенного выполнения
- `workflowId` - ID workflow
- `success` - статус запуска

**Примеры использования:**

- Запуск сложной оркестрации облачных функций из n8n
- Передача данных между n8n и Yandex Workflows
- Триггер long-running процессов
- Интеграция с существующими Workflows definitions

**Аутентификация:** Service account JSON через `yandexCloudAuthorizedApi` для создания SDK сессии. Автоматически валидирует JSON перед отправкой. Поддерживает resource locator для удобного выбора workflows с отображением описания. Нода подходит для создания комплексных автоматизаций, где n8n управляет внешними интеграциями и API, а Yandex Workflows координирует облачные ресурсы (Functions, Containers, Compute), обеспечивая визуальное проектирование сложных бизнес-процессов с обработкой ошибок, retry-логикой и параллельным выполнением задач.

## Yandex Cloud YDB

**Нода для работы с Yandex Database (YDB) — распределённой SQL-базой данных с автоматическим горизонтальным масштабированием и высокой доступностью.** Предоставляет возможность выполнения YQL (Yandex Query Language) запросов с привязкой параметров, автоматическим преобразованием типов и поддержкой множественных наборов результатов.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Query |
| **Operation** | Options | Execute или Execute with Parameters |
| **YQL Query** | String | YQL запрос для выполнения |
| **Return Mode** | Options | All Result Sets, First Result Set или First Row Only |

**Операции:**

- **Execute** — выполнить простой YQL запрос без параметров
- **Execute with Parameters** — выполнить параметризованный запрос с безопасной привязкой параметров

**Параметры запроса (для Execute with Parameters):**

Коллекция параметров запроса с настройкой:

- `name` — имя параметра (без префикса $)
- `value` — значение параметра (автоматически конвертируется в соответствующий тип YDB)

**Режимы возврата данных:**

- **All Result Sets** — возвращает все наборы результатов из мультизапросов
  - Возвращает: `resultSets` (массив наборов), `resultSetCount`, `totalRows`
- **First Result Set** — возвращает только первый набор результатов в виде массива
  - Возвращает: `rows` (массив строк), `rowCount`
- **First Row Only** — возвращает только первую строку первого набора результатов
  - Возвращает: единственный объект или null

**Преобразование типов:**

Автоматическое двунаправленное преобразование между типами JavaScript и YDB:

| JavaScript | Тип YDB | Пример |
|-----------|----------|---------|
| string | Text/String | "hello" → Text |
| number (int) | Int32 | 42 → Int32 |
| number (float) | Double | 3.14 → Double |
| bigint | Int64 | 9007199254740991n → Int64 |
| boolean | Bool | true → Bool |
| Date | Datetime | new Date() → Datetime |
| Array | List | [1,2,3] → List<Int32> |
| Object | Struct | {a:1} → Struct<a:Int32> |
| null | Null/Optional | null → Optional |

**Примеры запросов:**

*Простой запрос:*

```sql
SELECT id, name, email FROM users WHERE active = true LIMIT 10
```

*Параметризованный запрос:*

```sql
SELECT * FROM orders WHERE user_id = $userId AND order_date >= $startDate
```

Параметры: `userId` = 12345, `startDate` = "2025-01-01"

*Пакетная вставка:*

```sql
UPSERT INTO products SELECT * FROM AS_TABLE($rows)
```

Параметры: `rows` = массив объектов продуктов

*Множественные наборы результатов:*

```sql
SELECT COUNT(*) as total_users FROM users;
SELECT COUNT(*) as total_orders FROM orders;
SELECT COUNT(*) as total_products FROM products;
```

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

Нода YDB использует подход с двойными credentials для улучшенной безопасности и гибкости:

1. **Yandex Cloud Authorized API** (Обязательно)
   - Предоставляет Service Account JSON для аутентификации
   - Используется совместно с несколькими сервисами Yandex Cloud
   - Генерирует IAM-токены для безопасного доступа

2. **Yandex Cloud YDB API** (Обязательно)
   - Предоставляет параметры подключения к YDB (Endpoint и Database)
   - Отделяет параметры подключения от аутентификации
   - Позволяет легко переключаться между базами данных (dev/staging/prod)
   - Переиспользуется между нодами с одной базой данных

Такое разделение позволяет использовать один service account с несколькими базами данных YDB, сохраняя четкие границы безопасности.

**Процесс выполнения:**

1. Парсинг credentials service account JSON
2. Генерация IAM токена через Yandex Cloud IAM сервис
3. Создание YDB драйвера с аутентификацией
4. Конвертация JavaScript параметров в типы YDB используя @ydbjs/value
5. Выполнение YQL запроса через @ydbjs/query
6. Конвертация наборов результатов YDB обратно в JavaScript объекты
7. Возврат данных согласно выбранному режиму
8. Закрытие соединения драйвера

**Возвращаемые данные:**

Зависит от режима возврата:

- **All Result Sets**: `{resultSets: [[...], [...]], resultSetCount: 2, totalRows: 15}`
- **First Result Set**: `{rows: [{id: 1, name: "Alice"}, ...], rowCount: 10}`
- **First Row Only**: `{id: 1, name: "Alice", email: "alice@example.com"}` или `null`

**Варианты использования:**

- Аналитические запросы в реальном времени
- Агрегация данных и отчётность
- Управление пользовательскими данными (CRUD операции)
- Сложные соединения и трансформации
- ETL-процессы со структурированными данными
- Слой данных для микросервисов
- Event sourcing и журналы аудита
- Мультитенантные SaaS базы данных
- Транзакционные нагрузки с сильной согласованностью

**Лучшие практики:**

- Всегда используйте параметризованные запросы для динамических значений (предотвращает SQL инъекции)
- Используйте AS_TABLE для пакетных операций (эффективнее индивидуальных вставок)
- Используйте индексы YDB для лучшей производительности запросов
- Мониторьте статистику запросов через возвращаемые данные
- Обрабатывайте ошибки корректно с режимом Continue on Fail
- Рассмотрите использование First Row Only для агрегатов и подсчётов
- Используйте YDB-специфичные функции как UPSERT для идемпотентных операций

**Использование:** Требует оба credentials: `yandexCloudAuthorizedApi` (аутентификация service account) и `yandexCloudYdbApi` (параметры подключения). Использует Yandex Cloud IAM для генерации токенов и @ydbjs SDK для подключения к базе данных. Нода идеальна для создания data-driven приложений, аналитических дашбордов, систем управления пользователями и любых сценариев, требующих распределённую SQL базу данных с горизонтальным масштабированием, сильной согласованностью и встроенной репликацией в n8n workflow.

---

## Yandex Cloud Search

**Нода для работы с Yandex Cloud Search API, предоставляющая возможности веб-поиска и AI-генеративного поиска.** Использует официальный Yandex Cloud SDK для доступа к поисковым сервисам с поддержкой потоковой передачи для генеративных ответов и автоматическим парсингом XML для результатов веб-поиска.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Operation** | Options | Веб-поиск или Генеративный поиск |
| **Folder ID** | String | ID каталога (по умолчанию из credentials) |

**Операции:**

### Веб-поиск (Web Search)

Выполнение традиционных веб-поисковых запросов с обширными возможностями фильтрации и настройки.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Query** | String | Текст поискового запроса (обязательно) |
| **Search Type** | Options | RU, TR, COM, KK, BY, UZ (по умолчанию: RU) |

**Дополнительные опции:**

- **Family Mode** - Фильтрация контента (None, Moderate, Strict)
- **Page Number** - Страница результатов (от 0, по умолчанию: 0)
- **Fix Typos** - Автоисправление опечаток (Auto, Disabled)
- **Sort By** - Сортировка по релевантности или времени
- **Sort Order** - По возрастанию или убыванию (для сортировки по времени)
- **Group By** - Плоская группировка или по домену
- **Groups on Page** - Количество групп на странице (по умолчанию: 10)
- **Docs in Group** - Документов в группе (по умолчанию: 1)
- **Max Passages** - Максимум пассажей в сниппете (по умолчанию: 2)
- **Region** - ID региона поиска (например, 213 для Москвы)
- **Localization** - Язык интерфейса (RU, UK, BE, KK, TR, EN)
- **Response Format** - XML или HTML (по умолчанию: XML)
- **Parse XML to JSON** - Автоматически парсить XML ответ (по умолчанию: true)

**Возвращает:**

- `rawData` - Сырой XML/HTML ответ от поискового API
- `parsedData` - Распарсенная JSON структура (когда parseXml включён)
- `parseError` - Сообщение об ошибке, если парсинг XML не удался

### Генеративный поиск (Generative Search)

AI-поиск с генерацией естественноязыковых ответов на основе результатов поиска.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Messages** | Collection | Сообщения диалога с ролью (User/Assistant) и контентом |

**Дополнительные опции:**

- **Search Type** - RU, TR, COM, KK, BY, UZ
- **Site Restriction** - Ограничить поиск конкретным сайтом (например, example.com)
- **Host Restriction** - Ограничить конкретным хостом (например, <www.example.com>)
- **URL Restriction** - Ограничить конкретным URL путём
- **Fix Misspell** - Автоматически исправлять опечатки в запросе
- **Enable NRFM Docs** - Включить документы не с главной страницы
- **Get Partial Results** - Стримить частичные результаты во время обработки

**Возвращает:**

- `responses` - Массив всех полученных потоковых ответов
- `finalResponse` - Последний ответ с полным результатом
  - `message` - Текст сгенерированного ответа
  - `sources` - Массив использованных источников (url, title, used флаг)
  - `searchQueries` - Уточнённые запросы, использованные для генерации
  - `fixedMisspellQuery` - Исправленный запрос, если были опечатки
  - `isAnswerRejected` - Был ли ответ отклонён по этическим причинам
  - `isBulletAnswer` - Ответ в формате маркированного списка

**Пример диалога:**

```json
{
  "messages": [
    { "role": "USER", "content": "Что такое n8n?" },
    { "role": "ASSISTANT", "content": "n8n это инструмент автоматизации workflow..." },
    { "role": "USER", "content": "Как его установить?" }
  ]
}
```

**Процесс выполнения:**

1. Парсинг JSON credentials service account с валидацией
2. Создание аутентифицированной SDK сессии
3. Выполнение операции поиска через соответствующий service client
4. Для веб-поиска: парсинг XML ответа в JSON (если включено)
5. Для генеративного поиска: накопление потоковых ответов
6. Возврат структурированных результатов с pairedItem ссылками

**Ключевые возможности:**

- **Поддержка стриминга** - Генеративный поиск использует потоковую передачу на стороне сервера для прогрессивных результатов
- **Парсинг XML** - Автоматическая конвертация XML ответов в JSON для упрощения обработки
- **Многосообщенческий контекст** - Поддержка диалогового поиска с историей
- **Гибкая фильтрация** - Обширные опции для уточнения результатов поиска
- **Атрибуция источников** - Отслеживание использованных источников в генеративных ответах
- **Устойчивость к ошибкам** - Корректная обработка ошибок с поддержкой Continue on Fail

**Аутентификация:** Использует service account JSON через credentials `yandexCloudAuthorizedApi`. Валидирует все обязательные поля credentials (serviceAccountId, accessKeyId, privateKey) и folder ID. Поддерживает переопределение folder ID на уровне ноды. Нода идеальна для создания поисковых приложений, исследовательских инструментов, систем обнаружения контента, AI-ассистентов с веб-знаниями и любых сценариев, требующих интеграцию поиска с настраиваемой релевантностью и фильтрацией в n8n workflow.

---

## Yandex Cloud Vision OCR

**Нода для распознавания текста на изображениях с использованием Yandex Cloud Vision OCR API, обеспечивающая высокоточное оптическое распознавание символов с поддержкой множества языков и форматов.** Поддерживает файлы JPEG, PNG и PDF с автоматическим определением MIME-типа и гибким форматированием вывода.

| Параметр | Тип | Описание |
|----------|-----|----------|
| **Resource** | Options | Text Recognition (Распознавание текста) |
| **Operation** | Options | Recognize (Распознать) |
| **Binary Property** | String | Имя бинарного свойства с данными изображения (по умолчанию: "data") |
| **MIME Type** | Options | Автоопределение, JPEG, PNG или PDF |
| **Languages** | Multi-options | Языки для распознавания (формат ISO 639-1) |
| **Model** | Options | Выбор модели OCR (Page, Table, Markdown, Math Markdown) |
| **Output Format** | Options | Только полный текст, структурированные данные или оба варианта |

**Поддерживаемые языки:**

OCR поддерживает более 50 языков, организованных в две модели:

*Латино-кириллическая модель:*

- Английский, Русский, Немецкий, Французский, Испанский, Итальянский, Португальский, Голландский, Польский
- Чешский, Словацкий, Болгарский, Сербский, Боснийский, Румынский, Венгерский
- Шведский, Норвежский, Датский, Финский, Эстонский, Латышский, Литовский
- Турецкий, Азербайджанский, Казахский, Узбекский, Таджикский, Киргизский, Татарский, Башкирский, Якутский, Чувашский
- Индонезийский, Мальтийский, Словенский

*Другие модели (с поддержкой русского и английского):*

- Арабский, Китайский, Японский, Корейский, Тайский, Вьетнамский
- Иврит, Греческий, Армянский, Грузинский

Все языки используют коды формата ISO 639-1 (например, 'en', 'ru', 'de')

**Модели OCR:**

*Модели общего распознавания текста:*

- **Page** - Универсальное распознавание текста для документов и изображений (по умолчанию)
- **Page Column Sort** - Распознавание многоколоночного текста
- **Handwritten** - Оптимизировано для распознавания рукописного текста
- **Table** - Оптимизировано для распознавания табличных данных и структурированных макетов
- **Markdown** - Возвращает распознанный текст в формате markdown
- **Math Markdown** - Специализировано для математических формул и уравнений в markdown

*Модели распознавания шаблонных документов:*

- **Passport** - Шаблонное распознавание паспортов
- **Driver License Front** - Шаблонное распознавание водительского удостоверения (лицевая сторона)
- **Driver License Back** - Шаблонное распознавание водительского удостоверения (обратная сторона)
- **Vehicle Registration Front** - Шаблонное распознавание свидетельства о регистрации ТС (лицевая сторона)
- **Vehicle Registration Back** - Шаблонное распознавание свидетельства о регистрации ТС (обратная сторона)
- **License Plates** - Распознавание регистрационных номеров автомобилей

**Поддержка форматов файлов:**

- **JPEG** - Стандартные JPEG изображения
- **PNG** - PNG изображения с поддержкой прозрачности
- **PDF** - Одностраничные PDF документы
- Максимальный размер файла: 10МБ
- Максимальные размеры изображения: 20М пикселей (ширина × высота)

**Форматы вывода:**

1. **Только полный текст** - Простая строка со всем распознанным текстом
   - Возвращает: `{ fullText: "распознанный текст..." }`

2. **Структурированные данные** - Детальная структура с координатами и метаданными
   - Возвращает: `{ structured: [{ page, width, height, blocks, entities, tables, markdown, pictures }] }`
   - Включает ограничивающие рамки для блоков, строк и слов
   - Предоставляет распознавание ячеек таблиц с индексами строк/столбцов
   - Определяет сущности и картинки с оценками достоверности

3. **Оба** - Комбинированный вывод с полным текстом и структурированными данными
   - Возвращает: `{ fullText: "...", structured: [...] }`

**Процесс распознавания:**

1. Получение данных изображения из указанного бинарного свойства
2. Автоопределение или использование указанного MIME-типа
3. Валидация размера файла (макс. 10МБ)
4. Валидация требований модели (напр., license-plates требует явного указания языка)
5. Отправка запроса на распознавание с предпочтениями языка и выбором модели
6. Потоковая передача фрагментов ответа от OCR API
7. Объединение результатов для многостраничных PDF
8. Форматирование вывода согласно выбранному формату

**Возвращаемые данные (полный текст):**

- `fullText` - Полный распознанный текст со всех страниц

**Возвращаемые данные (структурированные):**

- `structured` - Массив аннотаций страниц
  - `page` - Номер страницы (начиная с 1)
  - `width` / `height` - Размеры изображения в пикселях
  - `blocks` - Текстовые блоки с ограничивающими рамками, строками, словами, языками
  - `entities` - Именованные сущности, обнаруженные в тексте
  - `tables` - Распознанные таблицы с данными ячеек (индексы строк/столбцов, объединения, текст)
  - `markdown` - Текст в формате markdown (если модель поддерживает)
  - `pictures` - Обнаруженные местоположения картинок с оценками достоверности
  - `rotate` - Угол поворота изображения (ANGLE_0, ANGLE_90, ANGLE_180, ANGLE_270)

**Детали структурированных данных:**

*Структура блока:*

- `boundingBox` - Вершины полигона, определяющего область блока
- `lines` - Массив текстовых строк со словами и ориентацией
- `languages` - Обнаруженные языки в блоке
- `layoutType` - Тип блока (TEXT, HEADER, FOOTER, TITLE, LIST и т.д.)

*Структура таблицы:*

- `rowCount` / `columnCount` - Размерность таблицы
- `cells` - Массив ячеек таблицы с:
  - `rowIndex` / `columnIndex` - Позиция ячейки
  - `rowSpan` / `columnSpan` - Объединение ячеек
  - `text` - Содержимое ячейки

**Сценарии использования:**

- Оцифровка и архивирование документов
- Обработка счетов и чеков
- Извлечение данных из удостоверений личности и паспортов
- Извлечение табличных данных из изображений
- Извлечение текста из отсканированных документов
- Обработка многоязычных документов
- Автоматизация обработки форм
- OCR для функций доступности
- Модерация контента с определением текста
- Распознавание номерных знаков (со структурированными координатами)

**Определение MIME-типа:**

Нода автоматически определяет формат изображения, анализируя магические байты:

- JPEG: заголовок `FF D8 FF`
- PNG: заголовок `89 50 4E 47`
- PDF: заголовок `25 50 44 46`
- По умолчанию использует JPEG, если определение не удалось

**Обработка ошибок:**

- Валидирует наличие и размер бинарных данных
- Проверяет лимит размера файла (10МБ)
- Валидирует требования конкретных моделей (напр., license-plates требует явного указания языка)
- Валидирует учетные данные сервисного аккаунта
- Поддерживает режим Continue on Fail для пакетной обработки
- Возвращает подробные сообщения об ошибках с контекстом

**Поддержка многостраничных PDF:**

Для PDF файлов с несколькими страницами нода:

- Обрабатывает каждую страницу отдельно
- Объединяет полный текст с разделителями в виде двойного переноса строки
- Возвращает массив структурированных данных с номерами страниц
- Сохраняет метаданные и координаты для каждой страницы

**Аутентификация:** Использует service account JSON через credentials `yandexCloudAuthorizedApi` с автоматической генерацией IAM токена. Использует gRPC потоковую передачу для эффективной передачи данных. Подключается к `ocr.api.cloud.yandex.net:443` для запросов распознавания. Нода идеальна для создания workflow обработки документов, конвейеров извлечения данных, автоматизации форм, систем обработки счетов и любых приложений, требующих точного распознавания текста из изображений с поддержкой сложных макетов, таблиц и математических обозначений в n8n workflow.

---

## Yandex Cloud Logging

**Нода для централизованного управления логами с помощью сервиса Yandex Cloud Logging, предоставляющая операции записи и чтения логов.** Поддерживает структурированное логирование с JSON-данными, фильтрацию по времени и организацию по ресурсам с автоматической пагинацией и пакетными операциями.

| Параметр | Тип | Ресурсы | Операции |
|----------|-----|---------|----------|
| **Log Entry** | Resource | Log Entry | Write, Read |

**Операции с записями логов:**

- **Write** - отправка записей в лог-группу с поддержкой:
  - Множественных записей в одном запросе
  - Уровней логирования (TRACE, DEBUG, INFO, WARN, ERROR, FATAL)
  - Автоматических или пользовательских меток времени
  - JSON-данных для структурированной информации
  - Имён потоков для организации логов
  - Метаданных ресурсов (тип и ID)
  - Значений по умолчанию для уровня, данных и потока

- **Read** - получение записей логов с фильтрацией:
  - Фильтрация по временному диапазону (since/until)
  - Фильтрация по уровням логирования (множественный выбор)
  - Фильтрация по типу и ID ресурса
  - Фильтрация по именам потоков
  - Расширенные выражения фильтрации
  - Автоматическая поддержка пагинации
  - Возврат всех записей или с ограничением

**Параметры записи:**

- `logGroupId` - целевая лог-группа (resource locator с выпадающим списком)
- `entries` - массив записей логов с:
  - `message` - текст лог-сообщения (обязательно)
  - `level` - уровень логирования (TRACE/DEBUG/INFO/WARN/ERROR/FATAL)
  - `timestamp` - формат ISO 8601 или автоматическая генерация
  - `jsonPayload` - структурированные данные как JSON-объект
  - `streamName` - поток для организации логов
- `resourceType` / `resourceId` - опциональные метаданные ресурса
- `defaults` - уровень, данные и поток по умолчанию для всех записей

**Параметры чтения:**

- `logGroupId` - исходная лог-группа (resource locator)
- `returnAll` - получить все страницы или ограничить результаты
- `limit` - максимальное количество записей (1-1000)
- `filters` - опциональная фильтрация:
  - `since` / `until` - временной диапазон (ISO 8601)
  - `levels` - уровни логирования для включения
  - `resourceTypes` - список типов ресурсов через запятую
  - `resourceIds` - список ID ресурсов через запятую
  - `streamNames` - список имён потоков через запятую
  - `filter` - расширенное выражение фильтрации

**Возвращаемые данные (Write):**

- `success` - статус операции
- `entriesWritten` - количество записанных записей
- `logGroupId` - ID целевой лог-группы
- `errors` - карта ошибок на уровне записей

**Возвращаемые данные (Read):**

Каждая запись лога возвращается как отдельный элемент с:

- `uid` - уникальный ID записи
- `message` - лог-сообщение
- `level` - уровень логирования
- `timestamp` - метка времени записи
- `resource` - метаданные ресурса (type, id)
- `jsonPayload` - структурированные данные
- `streamName` - имя потока
- `ingestedAt` - метка времени приёма
- `savedAt` - метка времени сохранения

**Сценарии использования:**

- Централизованное логирование приложений
- Мониторинг и оповещение об ошибках
- Аудит и логирование для соответствия требованиям
- Агрегация логов распределённых систем
- Конвейеры анализа логов в реальном времени
- Мониторинг производительности и метрик
- Логирование событий безопасности
- Устранение неполадок и отладка

**Возможности:**

- **Пакетная запись** - отправка множественных записей в одном запросе
- **Структурированное логирование** - JSON-данные для богатой информации
- **Фильтрация по времени** - точные запросы по временному диапазону
- **Организация по ресурсам** - группировка логов по типу/ID ресурса
- **Поддержка потоков** - организация логов по компонентам приложения
- **Автоматическая пагинация** - обработка больших наборов результатов
- **Resource Locator** - удобный выбор лог-группы из выпадающего списка

**Аутентификация:** Использует service account JSON через credentials `yandexCloudAuthorizedApi` с автоматической генерацией IAM токена. Требуется роль `logging.writer` для записи логов и `logging.reader` для чтения логов. Нода идеальна для создания систем наблюдаемости, дашбордов мониторинга, workflow анализа логов, конвейеров оповещений и любых приложений, требующих централизованного структурированного логирования с мощными возможностями фильтрации и запросов в n8n workflow.

---

## Yandex Cloud YandexART

**Нода для генерации изображений с помощью AI, используя API Yandex Cloud Foundation Models YandexART.** Создавайте высококачественные изображения из текстовых описаний с поддержкой негативных промптов, различных соотношений сторон и воспроизводимых результатов с помощью сидов. Включает обработку асинхронных операций с автоматическим опросом до завершения.

| Параметр | Тип | Ресурсы | Операции |
|----------|-----|---------|----------|
| **Image** | Resource | Image | Generate |

**Операции с изображениями:**

- **Generate** - создание изображений из текстовых промптов с:
  - Текстовым описанием (промпт) желаемого изображения
  - Негативным промптом для указания нежелательных элементов
  - Настраиваемым соотношением сторон (Квадрат, Альбомная 16:9, 21:9, Портретная 9:16, 9:21)
  - Выбором формата вывода (JPEG, PNG)
  - Опциональным сидом для воспроизводимой генерации
  - Автоматическим опросом операции до завершения
  - Возвратом сгенерированного изображения как бинарных данных

**Параметры генерации:**

- `prompt` - текстовое описание изображения для генерации (обязательно)
- **Дополнительные опции:**
  - `negativePrompt` - описание того, что нужно исключить из изображения (опционально)
  - `mimeType` - формат вывода: JPEG или PNG (по умолчанию: JPEG)
  - `aspectRatio` - пропорции изображения:
    - Квадрат (1:1)
    - Альбомная 16:9 (широкоэкранная)
    - Альбомная 21:9 (ультраширокая)
    - Портретная 9:16 (для мобильных)
    - Портретная 9:21 (высокий формат)
  - `seed` - числовой сид для воспроизводимости (опционально)
- **Расширенные опции:**
  - `waitForCompletion` - ожидать завершения генерации или вернуть ID операции (по умолчанию: true)
  - `pollInterval` - миллисекунды между проверками статуса (по умолчанию: 2000)
  - `maxWaitTime` - максимальное время ожидания в миллисекундах (по умолчанию: 300000 / 5 минут)

**Возвращаемые данные (с ожиданием завершения):**

- `success` - статус операции (true)
- `operationId` - ID операции Yandex Cloud
- `modelVersion` - версия модели YandexART
- `prompt` - оригинальный текст промпта
- `negativePrompt` - негативный промпт, если указан
- `aspectRatio` - ключ соотношения сторон (например, "SQUARE")
- `aspectRatioValues` - значения ширины и высоты соотношения
- `mimeType` - MIME тип сгенерированного изображения
- `seed` - использованный сид (число или "auto")
- `imageSize` - размер изображения в байтах
- `filename` - сгенерированное имя файла
- `binary.data` - сгенерированное изображение как загружаемый файл

**Возвращаемые данные (без ожидания):**

- `success` - статус операции (true)
- `operationId` - ID операции для ручной проверки статуса
- `done` - статус завершения операции (false)
- `message` - информационное сообщение
- `prompt` - оригинальный текст промпта
- `aspectRatio` - ключ соотношения сторон
- `mimeType` - запрошенный MIME тип

**Обработка асинхронных операций:**

Нода реализует автоматический опрос для асинхронных операций:

1. Отправляет запрос на генерацию в API YandexART
2. Получает ID операции
3. Опрашивает статус операции каждые 2 секунды (настраивается)
4. Продолжает опрос до завершения или таймаута
5. Извлекает сгенерированное изображение из завершённой операции
6. Возвращает изображение как бинарные данные с метаданными

Если `waitForCompletion` равно false, немедленно возвращает ID операции для ручной проверки статуса.

**Сценарии использования:**

- Создание маркетингового контента (изображения продуктов, баннеры, рекламу)
- Генерация визуального контента для социальных сетей
- Иллюстрации и концепт-арт для блогов и статей
- Прототипы макетов и дизайн-концепты
- Визуализация образовательных материалов
- Творческие workflow и художественные проекты
- Автоматизированные конвейеры визуального контента
- Генерация брендовых активов

**Возможности:**

- **Негативные промпты** - указание нежелательных элементов для лучшего контроля
- **Контроль соотношения сторон** - оптимизация для разных платформ и сценариев
- **Воспроизводимые результаты** - использование сидов для повторной генерации точных изображений
- **Множество форматов** - вывод в JPEG или PNG
- **Автоматический опрос** - бесшовная обработка асинхронных операций
- **Бинарный вывод** - сгенерированные изображения готовы для загрузки или дальнейшей обработки
- **Защита от таймаута** - настраиваемое максимальное время ожидания с понятными сообщениями об ошибках
- **Гибкий workflow** - может возвращать ID операции для ручной проверки

**Аутентификация:** Использует service account JSON через credentials `yandexCloudAuthorizedApi` с автоматической генерацией IAM токена. Требуется доступ к Foundation Models API в указанном каталоге. URI модели автоматически создаётся из ID каталога как `art://{folderId}/yandex-art/latest`. Нода идеальна для автоматизированного создания контента, маркетинговой автоматизации, творческих workflow и любых приложений, требующих AI-генерированного визуального контента, интегрированного в n8n workflow.

---

## Типы аутентификации

В пакете используются четыре типа credentials:

### yandexCloudYdbApi

- Endpoint (URL эндпоинта YDB)
- Database (путь к базе данных YDB)
- Используется для параметров подключения Yandex Cloud YDB (требует yandexCloudAuthorizedApi для аутентификации)

### yandexCloudGptApi

- API ключ для Foundation Models
- Folder ID
- URL эндпоинта (опционально)

### yandexCloudStaticApi

- Access Key ID
- Secret Access Key
- Используется для S3-совместимых сервисов (Object Storage, Data Streams, Message Queue, Postbox)

### yandexCloudAuthorizedApi

- Service Account JSON
- Folder ID
- Используется для сервисов, требующих IAM-токены (Functions, Containers, Compute, SpeechKit, Workflows, YDB)

---

## Yandex Cloud Lockbox

**Нода для безопасного управления секретами с использованием сервиса Yandex Cloud Lockbox.** Храните и получайте конфиденциальные данные, такие как API-ключи, пароли, сертификаты и токены с контролем версий, шифрованием и гранулированным управлением доступом. Поддерживает как текстовые, так и бинарные секреты с автоматической аутентификацией через IAM-токены.

| Параметр | Тип | Ресурсы | Операции |
|----------|-----|---------|----------|
| **Secret** | Ресурс | Secret | List, Get, Create, Update, Delete, Activate, Deactivate |
| **Version** | Ресурс | Version | List, Add, Schedule Destruction, Cancel Destruction |
| **Payload** | Ресурс | Payload | Get |

**Операции с секретами:**

- **List** - перечислить все секреты в каталоге с поддержкой пагинации
- **Get** - получить метаданные секрета по ID (имя, описание, статус, метки, версии)
- **Create** - создать новый секрет с начальной версией и записями payload
  - Поддержка текстовых и бинарных значений (base64)
  - Опциональная настройка ключа шифрования KMS
  - Метки для организации и фильтрации
  - Флаг защиты от удаления
- **Update** - изменить метаданные секрета (имя, описание, метки, защита от удаления)
- **Delete** - безвозвратно удалить секрет (учитывает защиту от удаления)
- **Activate** - изменить статус секрета с INACTIVE на ACTIVE
- **Deactivate** - изменить статус секрета с ACTIVE на INACTIVE

**Операции с версиями:**

- **List** - перечислить все версии конкретного секрета с пагинацией
- **Add** - создать новую версию с обновлёнными записями payload
  - Поддержка текстовых и бинарных значений
  - Опциональная ссылка на базовую версию
- **Schedule Destruction** - запланировать удаление версии с настраиваемым периодом ожидания (по умолчанию 7 дней)
- **Cancel Destruction** - отменить запланированное удаление версии

**Операции с payload:**

- **Get** - получить payload секрета (пары ключ-значение) по ID секрета
  - Опциональный ID версии (по умолчанию текущая версия)
  - Текстовые значения возвращаются как строки
  - Бинарные значения возвращаются в кодировке base64
- **Get by Name** - альтернативное получение payload через ID каталога + имя секрета
  - Полезно для workflow без ID секрета
  - Тот же формат вывода, что и у стандартной операции Get

**Параметры создания секрета:**

- `secretName` - уникальное имя секрета (обязательно)
- `description` - человекочитаемое описание (опционально)
- `payloadEntries` - пары ключ-значение с выбором типа (текст/бинарное)
- `deletionProtection` - предотвращение случайного удаления (по умолчанию: false)
- **Дополнительные опции:**
  - `labels` - метки ключ-значение для организации
  - `kmsKeyId` - ключ шифрования KMS для дополнительной безопасности
  - `versionDescription` - описание для начальной версии

**Аутентификация:** Использует JSON сервисного аккаунта через учётные данные `yandexCloudAuthorizedApi` с автоматическим управлением IAM-токенами. Поддерживает resource locators для удобного выбора секретов и версий из поисковых списков. Нода идеально подходит для безопасного управления учётными данными, хранения конфигураций, ротации сертификатов и соблюдения требований безопасности в автоматизированных workflow.

**Функции безопасности:**

- ✅ Неизменяемость версий - версии нельзя изменить после создания
- ✅ Защита от удаления - предотвращение случайного удаления секретов
- ✅ Шифрование KMS - шифрование секретов ключами, управляемыми клиентом
- ✅ Контроль доступа - гранулированные IAM-разрешения
- ✅ Аудит - все операции логируются через Cloud Logging
- ✅ Жизненный цикл версий - планирование удаления с периодом ожидания

---

## Общие возможности

Все ноды в пакете поддерживают:

- ✅ Continue on Fail - продолжение выполнения при ошибках
- ✅ Paired Items - сохранение связи между входными и выходными элементами
- ✅ Resource Locators - удобный выбор ресурсов из списков или ручной ввод
- ✅ Expressions - использование n8n expressions во всех параметрах
- ✅ Proxy Support - работа через HTTP/HTTPS прокси (где применимо)