بهینه‌سازی به‌روزرسانی و درج دسته‌ای سطرها در Airtable

Airtable Batch Update/Insert Rows: بهینه‌سازی فراخوانی‌های API

این گردش کار با دسته‌بندی کارآمد رکوردها، به‌روزرسانی و درج سطرها در Airtable را ساده می‌کند. این امر تعداد فراخوانی‌های API را به طور قابل توجهی کاهش می‌دهد که منجر به اجرای سریع‌تر و رعایت بهتر محدودیت‌های نرخ Airtable می‌شود.

دسته‌بندی‌ها: عملیات IT

کاتالوگ Axeto.ai: https://axeto.ai/n8n

---

۱. نمای کلی گردش کار

این گردش کار برای به‌روزرسانی دسته‌ای یا درج کارآمد سطرها در یک پایگاه Airtable با گروه‌بندی رکوردها در دسته‌های ۱۰ تایی طراحی شده است. هدف اصلی آن کاهش تعداد فراخوانی‌های API به Airtable، در نتیجه بهبود عملکرد و رعایت محدودیت‌های نرخ Airtable است.

گردش کار به بلوک‌های منطقی زیر سازماندهی شده است:

• ۱.۱ دریافت و آماده‌سازی ورودی: با فعال‌سازی دستی یا دریافت ورودی، راه‌اندازی داده‌ها و تجمیع اولیه آغاز می‌شود.
• ۱.۲ اجرای زیرگردش کار: یک گردش کار زیرین را اجرا می‌کند که دسته‌بندی و فراخوانی‌های واقعی API Airtable را مدیریت می‌کند.
• ۱.۳ پردازش دسته و انشعاب: رکوردها را به دسته‌هایی تقسیم می‌کند، آن‌ها را بر اساس حالت عملیات (upsert، insert، update) مسیریابی می‌کند و درخواست‌های HTTP را بر این اساس آماده می‌کند.
• ۱.۴ مدیریت درخواست API با محدودیت نرخ: درخواست‌های HTTP را با منطق تلاش مجدد و مدیریت محدودیت نرخ به API Airtable ارسال می‌کند.
• ۱.۵ تجمیع خروجی: پاسخ‌ها را از درخواست‌های دسته‌ای جمع‌آوری و ادغام می‌کند.

---

۲. تحلیل بلوک به بلوک

۲.۱ دریافت و آماده‌سازی ورودی

مرور کلی:

این بلوک گردش کار را به صورت دستی یا با داده‌های آزمایشی آغاز می‌کند، فیلدهای مورد نظر برای به‌روزرسانی/درج را تنظیم می‌کند و رکوردهای ورودی را برای پردازش دسته‌ای جمع‌آوری می‌کند.

گره‌های درگیر:

• When clicking ‘Test workflow’
• random data
• Set Fields
• Aggregate

جزئیات گره‌ها:

• When clicking ‘Test workflow’

* نوع: manualTrigger

* نقش: نقطه ورود برای اجرای دستی گردش کار جهت تست جریان.

* ورودی‌ها: ندارد

* خروجی‌ها: گره random data را فعال می‌کند.

* حالت‌های شکست: ندارد (تریگر دستی).

• random data

* نوع: debugHelper (داده تصادفی)

* نقش: تولید داده‌های آدرس تصادفی برای اهداف آزمایشی.

* ورودی‌ها: توسط تریگر دستی فعال می‌شود.

* خروجی‌ها: داده‌های نمونه برای پردازش تولید می‌کند.

* حالت‌های شکست: انتظار نمی‌رود.

* نکته: فقط برای نمایش/تست استفاده می‌شود.

• Set Fields

* نوع: set

* نقش: آماده‌سازی و تعریف فیلدهایی که با ستون‌های Airtable مطابقت دارند و باید به‌روزرسانی یا درج شوند.

* پیکربندی: کاربر باید جفت‌های کلید-مقدار را که دقیقاً با نام ستون‌های جدول Airtable مطابقت دارند (حساس به حروف بزرگ و کوچک و املا)، با انواع داده صحیح وارد کند.

* ورودی‌ها: از random data یا سایر منابع بالادستی.

* خروجی‌ها: داده‌های ساختاریافته را برای تجمیع به پایین‌دست ارسال می‌کند.

* حالت‌های شکست: نام‌ها یا انواع فیلدهای نامنطبق یا نادرست باعث خطاهای API در پایین‌دست می‌شوند.

* یادداشت چسبنده:

```markdown

## Set Fields

داده‌های ردیف خود را که می‌خواهید به Airtable ارسال کنید، وارد کنید. کلید باید با نام ستون دقیق مطابقت داشته باشد.

⚠️ فقط از فیلدهایی استفاده کنید که در جدول وجود دارند ⚠️

```

• Aggregate

* نوع: aggregate

* نقش: ترکیب تمام آیتم‌های ورودی در یک آرایه واحد تحت فیلد records.

* ورودی‌ها: از Set Fields.

* خروجی‌ها: خروجی تجمیع شده واحد از همه رکوردها.

* حالت‌های شکست: انتظار نمی‌رود.

---

۲.۲ اجرای زیرگردش کار

مرور کلی:

یک گردش کار زیرگردش کار اختصاصی را برای مدیریت پردازش دسته‌ای، تقسیم‌بندی و تعاملات API اجرا می‌کند. این رویکرد ماژولار، قابلیت استفاده مجدد و جداسازی منطق دسته‌ای را امکان‌پذیر می‌سازد.

گره‌های درگیر:

• Airtable Batch (اجرای گردش کار)

جزئیات گره‌ها:

• Airtable Batch

* نوع: executeWorkflow

* نقش: زیرگردش کار زیرمجموعه (با شناسه گردش کار یکسان) را با ورودی‌های mode، baseId، tableIdOrName، fieldsToMergeOn و records فراخوانی می‌کند.

* پیکربندی:

* mode: حالت عملیات (به طور پیش‌فرض upsert).

* baseId: شناسه پایگاه Airtable (کاربر مشخص می‌کند).

* tableIdOrName: شناسه یا نام جدول Airtable.

* fieldsToMergeOn: آرایه‌ای از نام فیلدها برای تطبیق رکوردها برای به‌روزرسانی/upsert.

* records: آرایه‌ای از رکوردها برای عملیات.

* ورودی‌ها: رکوردهای تجمیع شده از بلوک قبلی.

* خروجی‌ها: خروجی مستقیمی ندارد؛ زیرگردش کار مسئول فراخوانی API و بازگرداندن نتایج است.

* حالت‌های شکست: اعتبارنامه‌های نامعتبر، شناسه‌های پایگاه/جدول نادرست، یا ورودی‌های بدشکل ممکن است باعث شکست شوند.

---

۲.۳ پردازش دسته‌ای و انشعاب

مرور کلی:

در داخل زیرگردش کار، این بلوک رکوردها را به دسته‌های ۱۰ تایی تقسیم می‌کند، سپس هر دسته را بسته به حالت عملیات (upsert، insert، update) از مسیرهای مختلف هدایت می‌کند. هر مسیر داده‌ها را برای درخواست API مربوطه Airtable آماده می‌کند.

گره‌های درگیر:

• Airtable Subprocess (تریگر اجرای گردش کار)
• Split Out
• batch 10 (تقسیم به دسته‌ها)
• return merged output (کد)
• Switch
• Edit Fields1
• Edit Fields2
• Edit Fields4
• Aggregate1
• Aggregate2
• Aggregate3

جزئیات گره‌ها:

• Airtable Subprocess

* نوع: executeWorkflowTrigger

* نقش: نقطه ورود زیرگردش کار، پارامترها و رکوردها را دریافت می‌کند.

* ورودی‌ها: از Airtable Batch (گردش کار والد).

* خروجی‌ها: تمام رکوردها را به گره Split Out ارسال می‌کند.

* حالت‌های شکست: شمای ورودی نادرست ممکن است باعث خطا شود.

• Split Out

* نوع: splitOut

* نقش: آرایه records را از ورودی استخراج کرده و برای پردازش دسته‌ای آماده می‌کند.

* پیکربندی: فیلد records را به آیتم‌های جداگانه تقسیم می‌کند و فیلدهای دیگر را حفظ می‌کند.

* ورودی‌ها: از Airtable Subprocess.

* خروجی‌ها: رکوردهای جداگانه را به گره batch 10 ارسال می‌کند.

• batch 10

* نوع: splitInBatches

* نقش: رکوردهای ورودی را به دسته‌های ۱۰ تایی برای فراخوانی‌های کارآمد API تقسیم می‌کند.

* پیکربندی: اندازه دسته روی ۱۰ تنظیم شده است.

* ورودی‌ها: رکوردهای جداگانه از Split Out.

* خروجی‌ها: دسته‌ها را به return merged output و سپس گره Switch ارسال می‌کند.

• return merged output

* نوع: code (جاوا اسکریپت)

* نقش: خروجی‌های دسته را در یک شیء واحد شامل آرایه‌هایی برای همه records، updatedRecords و createdRecords از پاسخ‌های دسته ادغام می‌کند.

* ورودی‌ها: دسته‌ها از batch 10.

* خروجی‌ها: شیء ادغام شده را به گره Switch ارسال می‌کند.

* عبارت کلیدی: آرایه‌ها را از تمام دسته‌های ورودی الحاق می‌کند.

• Switch

* نوع: switch

* نقش: داده‌ها را بر اساس فیلد mode (update، upsert، insert) به گره Edit Fields مربوطه هدایت می‌کند.

* ورودی‌ها: داده‌های دسته ادغام شده از return merged output.

* خروجی‌ها:

* update → Edit Fields4

* upsert → Edit Fields1

* insert → Edit Fields2

• Edit Fields1 (upsert)

* نوع: set

* نقش: بار (payload) را برای فراخوانی API upsert آماده می‌کند.

* پیکربندی:

* records.fields را به تمام فیلدها در fields به جز id اختصاص می‌دهد.

* records.id را به مقدار فیلد id (در صورت وجود) تنظیم می‌کند.

* ورودی‌ها: از Switch (مسیر upsert).

* خروجی‌ها: به Aggregate1.

• Edit Fields2 (insert)

* نوع: set

* نقش: بار (payload) را برای فراخوانی API insert آماده می‌کند.

* پیکربندی: تمام فیلدها را همانطور که هستند به records.fields اختصاص می‌دهد.

* ورودی‌ها: از Switch (مسیر insert).

* خروجی‌ها: به Aggregate2.

• Edit Fields4 (update)

* نوع: set

* نقش: بار (payload) را برای فراخوانی API update آماده می‌کند.

* پیکربندی: مشابه Edit Fields1، فیلدها به جز id را اختصاص می‌دهد و records.id را تنظیم می‌کند.

* ورودی‌ها: از Switch (مسیر update).

* خروجی‌ها: به Aggregate3.

• Aggregate1, Aggregate2, Aggregate3

* نوع: aggregate

* نقش: خروجی‌های دسته را برای حالت‌های مربوطه قبل از ارسال درخواست‌های API جمع‌آوری می‌کند.

* ورودی‌ها: از گره‌های Edit Fields مربوطه.

* خروجی‌ها: به گره‌های درخواست HTTP (upsert، insert، update).

---

۲.۴ مدیریت درخواست API با محدودیت نرخ

مرور کلی:

این بلوک درخواست‌های HTTP را به API Airtable برای هر دسته اجرا می‌کند، خطاهای محدودیت نرخ (HTTP 429) را مدیریت می‌کند و برای جلوگیری از تجاوز از محدودیت‌ها، درخواست‌ها را با وقفه‌های مناسب مجدداً امتحان می‌کند.

گره‌های درگیر:

• upsert (درخواست HTTP)
• insert (درخواست HTTP)
• update (درخواست HTTP)
• rate limit? (اگر)
• rate limit?1 (اگر)
• rate limit?2 (اگر)
• Wait 5s, Wait 5s1, Wait 5s2 (انتظار)
• Wait 0.2s to prevent rate limits (انتظار)
• retry request, retry request1, retry request2 (ادغام)

جزئیات گره‌ها:

• upsert, insert, update

* نوع: httpRequest

* نقش: بسته به حالت، درخواست‌های PATCH یا POST را به API Airtable ارسال می‌کند.

* پیکربندی:

* URL به صورت پویا از ورودی‌های baseId و tableIdOrName ساخته می‌شود.

* متد: PATCH برای upsert و update، POST برای insert.

* بدنه: JSON با رکوردهای آماده شده در بلوک‌های قبلی.

* احراز هویت: از اعتبارنامه توکن API Airtable استفاده می‌کند.

* تلاش‌های مجدد: تا ۵ تلاش مجدد با تأخیر ۵ ثانیه‌ای بین تلاش‌ها.

* ورودی‌ها: رکوردهای تجمیع شده از گره‌های Aggregate مربوطه یا ادغام‌های مجدد.

* خروجی‌ها: اشیاء پاسخ به بررسی‌های rate limit? ارسال می‌شوند.

* حالت‌های شکست: خطاهای شبکه، شکست‌های احراز هویت، داده‌های نامعتبر، محدودیت‌های نرخ (429).

• rate limit?, rate limit?1, rate limit?2

* نوع: if

* نقش: بررسی می‌کند که آیا کد وضعیت پاسخ HTTP 429 (خطای محدودیت نرخ) است یا خیر.

* ورودی‌ها: از گره‌های httpRequest مربوطه.

* خروجی‌ها:

* True (محدودیت نرخ اعمال شده) → گره انتظار (۵ ثانیه) یا انتظار کوتاه (۰.۲ ثانیه).

* False → گره‌های ادغام مجدد (retry request و غیره).

* حالت‌های شکست: تفسیر نادرست کدهای وضعیت.

• Wait 5s, Wait 5s1, Wait 5s2

* نوع: wait

* نقش: اجرای را برای ۵ ثانیه متوقف می‌کند تا قبل از تلاش مجدد، محدودیت‌های نرخ API رعایت شود.

* ورودی‌ها: خروجی True گره (محدودیت نرخ اعمال شده).

* خروجی‌ها: به گره‌های ادغام مجدد.

• Wait 0.2s to prevent rate limits

* نوع: wait

* نقش: تأخیر کوتاه (۰.۲ ثانیه) برای جلوگیری از رسیدن به محدودیت‌های نرخ در فراخوانی‌های بعدی.

* ورودی‌ها: خروجی‌های False گره‌های if محدودیت نرخ.

* خروجی‌ها: برای ادامه پردازش دسته.

• retry request, retry request1, retry request2

* نوع: merge

* نقش: درخواست‌های اصلی و مجدد را ترکیب می‌کند و شاخه صحیح را برای تلاش مجدد فراخوانی‌های ناموفق API انتخاب می‌کند.

* ورودی‌ها: از گره‌های Wait و httpRequest.

* خروجی‌ها: به گره‌های httpRequest برای اجرای مجدد.

* حالت‌های شکست: تلاش مجدد بی‌نهایت بالقوه در صورت ادامه شرایط محدودیت نرخ (باید نظارت شود).

---

۲.۵ تجمیع خروجی

مرور کلی:

تمام پاسخ‌های API دسته‌ای را تجمیع می‌کند تا خلاصه‌ای ترکیبی از رکوردهای درج شده و به‌روزرسانی شده را برگرداند.

گره‌های درگیر:

• return merged output (کد، در پردازش دسته)
• Aggregate (سطح بالا پس از Set Fields)

جزئیات گره‌ها:

• return merged output (قبلاً در ۲.۳ توضیح داده شده است)

* نتایج دسته را برای خروجی تمیزتر در پایین‌دست ادغام می‌کند.

• Aggregate (گره سطح بالا)

* تمام خروجی‌های دسته ورودی را قبل از فراخوانی زیرگردش کار برای پردازش دسته، تجمیع می‌کند.

---

۳. جدول خلاصه