🏠 Главная › user guide › productivity airtable

{/ Эта страница автоматически передается из навыков SKILL.md с помощью сайта/scripts/generate-skill-docs.py. Редактируйте исходный SKILL.md, а не эту страницу. /}

Воздушный стол

REST API Airtable через Curl. CRUD записи, фильтры, upsert.

Метаданные навыки
Источник Встроенный (устанавливается по умолчанию)
Путь навыки/производительность/airtable
Версия 1.1.0
Автор сообщество
Лицензия Массачусетский технологический институт
Платформы Linux, MacOS, Windows
Теги Airtable, Производительность, База данных, API

Справочник: полный SKILL.md:::информация

Ниже приведено полное описание навыка, который Hermes загружает при активации этого навыка. Это то, что агент видит в качестве инструкций, когда навыки активны.

Airtable — Базы, Таблицы и Записи

Работайте с REST API Airtable напрямую через «curl» с помощью инструмента «терминал». Никакого MCP-сервера, никакого OAuth-потока, никакого Python SDK — просто «curl» и персональный токен доступа.

Предварительные требования

  1. Создайте Персональный токен доступа (PAT) на https://airtable.com/create/tokens (токены начинаются с pat...).
  2. Предоставьте следующее разрешение (минимум):
  3. data.records:read — чтение строк
  4. data.records:write — создание/обновление/удаление строки
  5. schema.bases:read — список баз и таблиц
  6. Важно: в том же интерфейсе токена добавьте все приложения, к которым вы хотите получить доступ, в списке Доступ токена. PAT ограничен по базам — фактический токен для неправильной базы возвращает 403.
  7. Сохраните токен в ~/.hermes/.env (или через hermes setup): AIRTABLE_API_KEY=pat_your_token_here

    Примечание: конфиденциальность ключей API key... была объявлена ​​закрытыми в феврале 2024 года. Сейчас работают только PAT и OAuth-токены.

Основы API

Базовый шаблон завитка:

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=5" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

-s блокирует индикатор прогресса завитка — удерживает его включенным для каждого вызова, чтобы вывести инструмент стабильно чистым для Hermes. Запускайте через python3 -m json.tool (всегда присутствует) или jq (если установлен) для читаемого JSON.

Типы полей (формы запроса тела)

Тип поля Форма записи
Однострочный текст "Имя": "привет"
Длинный текст "Заметки": "multi\nline"
Число "Счет": 42
Флажок "Готово": правда
Одиночный выбор "Status": "Todo" (имя должно уже существовать, если не typecast: true)
Множественный выбор "Теги": ["срочно", "ошибка"]
Дата "Срок": "2026-04-01"
Дата и время (UTC) "В": "2026-04-01T14:30:00.000Z"
URL / Электронная почта / Телефон "Ссылка": "https://…"
Вложение "Files": [{"url": "https://…"}] (Airtable загружается и размещается у себя)
Связанная запись "Владелец": ["recXXXXXXXXXXXXXXX"] (массив идентификаторов записей)
Пользователь "AssignedTo": {"id": "usrXXXXXXXXXXXXXX"}

Передайте "typecast": true на верхний уровень создания/обновления тела, чтобы позволить Airtable автоматически преобразовывать значения (например, создать новый вариант выбора на лету, преобразовать "42" → 42).

Распространенные запросы

Список баз, которые видят токены

curl -s "https://api.airtable.com/v0/meta/bases" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Список таблиц + схема для базы

curl -s "https://api.airtable.com/v0/meta/bases/$BASE_ID/tables" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Используйте это ДО изменений — подтвердите точные имена и идентификаторы полей, покажите options.choices для выбора полей и имен первичных полей.

Список записей (первые 10)

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?maxRecords=10" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Получить одну запись

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Фильтрация записей (filterByFormula)

Формулы Airtable должны быть URL-закодированы. Пусть Python stdlib делает это — никогда не кодируйте вручную:

FORMULA="{Status}='Todo'"
ENC=$(python3 -c 'import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=""))' "$FORMULA")
curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?filterByFormula=$ENC&maxRecords=20" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Полезные шаблоны формулы: - Точное совпадение: {Email}='user@example.com' - Содержит: FIND('bug', LOWER({Title})) - Несколько условий: AND({Status}='Todo', {Priority}='High') - Или: OR({Owner}='alice', {Owner}='bob') - Не пусто: NOT({Assignee}='') - Сравнение дат: IS_AFTER({Срок}, TODAY())

Сортировка + выбор европейских полей

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?sort%5B0%5D%5Bfield%5D=Priority&sort%5B0%5D%5Bdirection%5D=asc&fields%5B%5D=Name&fields%5B%5D=Status" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Квадратные скобки в параметрах запроса ДОЛЖНЫ быть URL-закодированы (%5B / %5D).

Использовать именное представление

curl -s "https://api.airtable.com/v0/$BASE_ID/$TABLE?view=Grid%20view&maxRecords=50" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Представление наших сохраненных фильтров + сортировка на стороне сервера.

Распространенные изменения

Создать запись

curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"Name":"Новая задача","Status":"Todo","Priority":"High"}}' | python3 -m json.tool

Создать до 10 записей за один вызов

curl -s -X POST "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "typecast": true,
    "records": [
      {"fields": {"Name": "Задача A", "Status": "Todo"}},
      {"fields": {"Name": "Задача B", "Status": "In progress"}}
    ]
  }' | python3 -m json.tool

Пакетные конечные точки ограничены 10 записями на запрос. Для больших вставок выполняйте цикл партиями по 10 с короткой паузой, чтобы соблюсти 5 запросов/сек/базу.

Обновить запись (PATCH — конверт, сохранить неизмененные поля)

curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fields":{"Status":"Done"}}' | python3 -m json.tool

Upsert по лю слиянию (ID не нужен)

curl -s -X PATCH "https://api.airtable.com/v0/$BASE_ID/$TABLE" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "performUpsert": {"fieldsToMergeOn": ["Email"]},
    "records": [
      {"fields": {"Email": "user@example.com", "Status": "Active"}}
    ]
  }' | python3 -m json.tool

performUpsert записывает значения полей слияния, которые новые, и обновляет записи, значения полей слияния, которые уже существуют. Отлично подходит для идемпотентных синхронизаций.

Удалить запись

curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE/$RECORD_ID" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Удалить до 10 записей за один вызов

curl -s -X DELETE "https://api.airtable.com/v0/$BASE_ID/$TABLE?records%5B%5D=rec1&records%5B%5D=rec2" \
  -H "Authorization: Bearer $AIRTABLE_API_KEY" | python3 -m json.tool

Пагинация

Конечная точка-ы возвращают максимум 100 записей на страницу. Если ответ включает "offset": "...", передайте его обратно в следующем вызове. Выполните цикл, пока отсутствует поле:

OFFSET=""
while:; do
  URL="https://api.airtable.com/v0/$BASE_ID/$TABLE?pageSize=100"
  [ -n "$OFFSET" ] && URL="$URL&offset=$OFFSET"
  RESP=$(curl -s "$URL" -H "Authorization: Bearer $AIRTABLE_API_KEY")
  echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); [print(r["id"], r["fields"].get("Name","")) for r in d["records"]]'
  OFFSET=$(echo "$RESP" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(d.get("offset",""))')
  [ -z "$OFFSET" ] && break
done

Типичный рабочий процесс Hermes

  1. Подтвердите аутентификацию. curl -s -o /dev/null -w "%{http_code}\n" https://api.airtable.com/v0/meta/bases -H "Авторизация: Носитель $AIRTABLE_API_KEY" — ожидайте 200.
  2. Найдите ресурсы. Вы создайте список баз (шаг выше) ИЛИ запросите идентификатор пользователя app... напрямую, если у токена нет schema.bases:read.
  3. Проверьте схему. GET /v0/meta/bases/$BASE_ID/tables — кэшируйте точные имена полей и имя первого локального поля в сеансе перед любыми изменениями.
  4. Читайте перед записью. Для «обновить X, где Y» сначала используйте filterByFormula, чтобы получить идентификатор rec..., затем PATCH /v0/$BASE_ID/$TABLE/$RECORD_ID. Никогда не угадывайте идентификатор записи.
  5. Пакетная запись. Объедините создание связи в одном POST на 10 записей, чтобы оставаться в рамках бюджета 5 запросов/сек.
  6. Деструктивные операции невозможно. Удаления отмены через API. Если пользователь говорит «удалить все X», вы вводите обратно фильтр + количество записей и подтверждаете перед выполнением.

Подводные камни

Важные примечания для Hermes