Массовый API

Массовый API (bulk API) — это отдельный набор эндпоинтов, который поставщик предлагает для переноса множества записей разом, в отличие от поштучного API, обслуживающего обычный трафик приложения. Он существует потому, что у этих двух нагрузок нет ничего общего: одной нужна одна запись за миллисекунды, другой — перенести сто тысяч записей, и ей всё равно, в какой момент часа это закончится. Обращаться со второй как с быстрым циклом по первой — верный способ упереться в лимит запросов и встать на первой же исторической загрузке. Три различия важнее прочих. Массовый API обычно асинхронен: вы отправляете задание, получаете идентификатор, опрашиваете его состояние и затем скачиваете результат, а не читаете ответ, — значит, коду нужно место, где задание переживёт породивший его запрос. Он тарифицируется иначе, как правило по квоте заданий или строк, а не по лимиту запросов, поэтому бюджет, рассчитанный для обычного API, здесь неверен. И ошибки возвращаются по каждой записи: задание может отчитаться об успехе, когда часть строк отклонена валидацией, и это самый частый способ, которым массовый импорт превращается в проблему с данными спустя месяцы. Вызывающая сторона, смотрящая только на статус задания, записала частичный импорт как чистый. Мелкие различия подводят не реже. Покрытие полей нередко уже, чем у поштучного API: объект, который вы обычно создаёте, может быть недоступен для массового создания или доступен не со всеми атрибутами. Валидация иногда слабее, то есть массовый путь — это дверь, через которую в систему попадают записи, отвергнутые бы интерактивным API. Порядок внутри задания не гарантируется, поэтому пачку, содержащую и создание, и последующее обновление одной и той же записи, нельзя считать применяемой именно в этой последовательности. Практические привычки: всегда читайте результат по каждой записи и сверяйте количества, а не только статус задания; давайте каждому заданию ключ идемпотентности или собственный идентификатор пачки, чтобы повторная отправка после таймаута не записала всё дважды; подбирайте размер пачки под заявленный поставщиком максимум, а не под то, что помещается в память; и делайте первую боевую пачку такой, чтобы отказы мог прочитать человек.