گردش کار خودکار استخراج طرحواره API با n8n

API Schema Extractor

این گردش کار، کشف، استخراج و تولید طرحواره‌های API را از خدمات آنلاین مختلف خودکار می‌کند. این گردش کار برای تیم‌ها و پروژه‌هایی طراحی شده است که به کاتالوگ‌سازی و مستندسازی سیستماتیک API نیاز دارند و جستجوی وب، خراشیدن (scraping)، ذخیره‌سازی برداری (vector storage) و پردازش مدل‌های زبان بزرگ (LLM) را ادغام می‌کند.

موارد استفاده کلیدی:

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

مراحل گردش کار:

1. ورودی و مسیریابی رویداد: رویدادهای دستی یا خارجی را مدیریت کرده و وظایف را به مرحله مناسب (تحقیق، استخراج یا تولید) هدایت می‌کند.

2. مرحله ۱ - تحقیق: خدمات در انتظار را پیدا می‌کند، مستندات API را به صورت آنلاین جستجو می‌کند، محتوای وب مرتبط را خراش می‌دهد، یافته‌ها را فیلتر و حذف موارد تکراری می‌کند، محتوا را در یک فروشگاه برداری جاسازی (embed) می‌کند و پیشرفت را به‌روزرسانی می‌کند.

3. مرحله ۲ - استخراج: خدمات با تحقیق تکمیل شده را پردازش می‌کند، پایگاه داده برداری را برای اطلاعات مرتبط جستجو می‌کند، عملیات API را با استفاده از LLM استخراج می‌کند، این عملیات را ذخیره می‌کند و وضعیت آن‌ها را به‌روزرسانی می‌کند.

4. مرحله ۳ - تولید: عملیات API استخراج شده را بازیابی می‌کند، آن‌ها را در یک طرحواره JSON سفارشی جمع‌آوری می‌کند و فایل طرحواره را آپلود می‌کند.

---

تفکیک گردش کار

۱. ورودی و مسیریابی رویداد

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

گره‌ها (Nodes):

• Manual Trigger: گردش کار را به صورت دستی آغاز می‌کند.
• Set (Execution Data): فراداده‌های کلیدی مانند eventType، executedById و service را از JSON ورودی استخراج می‌کند.

* Key Expressions: $json.eventType، $json.executedById، $json.data.service

• Switch (EventRouter): گردش کار را بر اساس فیلد eventType به یکی از سه شاخه هدایت می‌کند: research، extract یا generate.

موارد مرزی (Edge Cases):

• مقادیر eventType گمشده یا غیرمنتظره، مسیریابی را متوقف خواهد کرد.

---

۲. مرحله ۱ - تحقیق (Research)

این مرحله بر یافتن و پردازش اطلاعات مربوط به APIها برای یک سرویس معین تمرکز دارد.

گره‌ها (Nodes):

• Google Sheets (Get All Research): سرویس‌هایی را که در انتظار تحقیق هستند، بازیابی می‌کند.
• If (All Research Done?): بررسی می‌کند که آیا سرویس دیگری برای تحقیق باقی مانده است یا خیر.
• SplitInBatches (For Each Research…): هر سرویس را به صورت جداگانه پردازش می‌کند.
• Google Sheets (Research Pending): وضعیت سرویس را در Google Sheets به "در انتظار تحقیق" (pending) به‌روزرسانی می‌کند.
• Set (Research Event): داده‌های رویداد را برای گردش کار فرعی تحقیق آماده می‌کند.
• Execute Workflow (Research): یک گردش کار فرعی را برای انجام تحقیق برای یک سرویس واحد اجرا می‌کند.
• HttpRequest (Web Search For API Schema): از Apify برای انجام جستجوی Google برای مستندات API استفاده می‌کند.
• If (Has Results?): بررسی می‌کند که آیا جستجوی وب نتایجی را برگردانده است یا خیر.
• SplitOut (Results to List): نتایج جستجو را به فرمت لیست تبدیل می‌کند.
• Filter (Filter Results): نتایج جستجو را فیلتر می‌کند تا فقط انواع مرتبط را شامل شود.
• RemoveDuplicates (Remove Dupes): ورودی‌های تکراری را بر اساس URL حذف می‌کند.
• HttpRequest (Scrape Webpage Contents): از Apify برای خراشیدن عنوان و محتوای HTML صفحات وب مرتبط استفاده می‌کند (دسته‌های ۲ صفحه‌ای هر ۳۰ ثانیه).
• If (Has Results?1): بررسی می‌کند که آیا خراشیدن محتوا تولید کرده است یا خیر.
• LLM (Has API Documentation?): از LLM Gemini برای طبقه‌بندی اینکه آیا محتوای خراشیده شده حاوی مستندات طرحواره API است یا خیر، استفاده می‌کند.
• If (Has Results?3): بررسی می‌کند که آیا LLM محتوا را به عنوان حاوی مستندات API طبقه‌بندی کرده است یا خیر.
• Set (Set Embedding Variables): فراداده و محتوا را برای جاسازی (embedding) آماده می‌کند.
• SplitInBatches (For Each Document…): هر بخش از محتوا را پردازش می‌کند.
• Set (Content Chunking @ 50k Chars): محتوا را برای پردازش به بخش‌های کوچک‌تر تقسیم می‌کند.
• SplitOut (Split Out Chunks): محتوا را به بخش‌های قابل مدیریت تقسیم می‌کند.
• Document Loader (Default Data Loader): داده‌ها را برای جاسازی آماده می‌کند.
• Embeddings (Embeddings Google Gemini): جاسازی‌ها را برای بخش‌های محتوا تولید می‌کند.
• Vector Store Qdrant (Store Document Embeddings): جاسازی‌های تولید شده را در فروشگاه برداری Qdrant ذخیره می‌کند.
• Google Sheets (Research Result / Research Error): نتیجه تحقیق ("ok" یا "error") را در Google Sheet به‌روزرسانی می‌کند.
• Wait (Wait): تاخیری را برای مدیریت سرعت اجرا معرفی می‌کند.

موارد مرزی و انواع شکست (Edge Cases & Failure Types):

• خطاهای احراز هویت یا مجوز Google Sheets.
• خطاهای API Apify یا محدودیت نرخ (rate limiting).
• عدم یافتن نتایج جستجو.
• خطاهای طبقه‌بندی یا مهلت زمانی LLM.
• شکست در درج فروشگاه برداری.
• خطاها یا مهلت زمانی اجرای گردش کار فرعی.

---

۳. مرحله ۲ - استخراج (Extraction)

این مرحله عملیات خاص API را از مستندات تحقیق شده استخراج می‌کند.

گره‌ها (Nodes):

• Google Sheets (Get All Extract): سرویس‌هایی را که تحقیق آن‌ها تکمیل شده اما استخراج هنوز انجام نشده است، بازیابی می‌کند.
• If (All Extract Done?): بررسی می‌کند که آیا سرویس‌هایی در انتظار استخراج وجود دارند یا خیر.
• SplitInBatches (For Each Extract…): هر سرویس را به صورت جداگانه پردازش می‌کند.
• Google Sheets (Extract Pending): وضعیت سرویس را در Google Sheets به "در انتظار استخراج" (pending) به‌روزرسانی می‌کند.
• Set (Extract Event): داده‌های رویداد را برای گردش کار فرعی استخراج آماده می‌کند.
• Execute Workflow (Extract): یک گردش کار فرعی را برای انجام استخراج برای یک سرویس واحد اجرا می‌کند.
• Set (Query Templates): الگوهایی را برای پرس‌وجو از اطلاعات تعریف می‌کند.
• SplitOut (Template to List): الگوهای پرس‌وجو را به لیست تبدیل می‌کند.
• LLM (Identify Service Products): از LLM Gemini برای شناسایی نام محصولات یا راه‌حل‌ها از اسناد فروشگاه برداری استفاده می‌کند.
• Set (Extract API Templates): رشته‌های پرس‌وجوی API را بر اساس محصولات/راه‌حل‌های شناسایی شده می‌سازد.
• SplitInBatches (For Each Template…): هر الگوی پرس‌وجوی API را پردازش می‌کند.
• Vector Store Qdrant (Search in Relevant Docs): فروشگاه برداری را برای اسناد مربوط به مستندات API جستجو می‌کند.
• Aggregate (Combine Docs): اسناد بازیابی شده را ترکیب می‌کند.
• Set (Query & Docs): پرس‌وجو و اسناد ترکیب شده را بسته‌بندی می‌کند.
• LLM Chat (Google Gemini Chat Model2): برای استخراج اولیه اطلاعات با Gemini تعامل می‌کند.
• SplitInBatches (For Each Template…1): هر الگو را دوباره برای استخراج عملیات دقیق پردازش می‌کند.
• LLM (Extract API Operations): از LLM Gemini برای استخراج نقاط پایانی خاص API، عملیات، توضیحات و متدها از مستندات استفاده می‌کند.
• Vector Store Qdrant (Search in Relevant Docs1): جستجوی دیگری را در فروشگاه برداری انجام می‌دهد.
• Aggregate (Combine Docs1): نتایج را ترکیب می‌کند.
• Set (Query & Docs1): پرس‌وجو و اسناد ترکیب شده را بسته‌بندی می‌کند.
• Embeddings (Embeddings Google Gemini1 & Embeddings Google Gemini2): جاسازی‌ها را تولید می‌کند (برای زمینه استفاده می‌شود، نه مستقیماً برای ذخیره‌سازی در اینجا).
• Code (Merge Lists): اطلاعات استخراج شده از مراحل مختلف را ادغام می‌کند.
• If (Has Operations?): بررسی می‌کند که آیا عملیات API استخراج شده است یا خیر.
• RemoveDuplicates (Remove Duplicates): عملیات تکراری را بر اساس متد و URL حذف می‌کند.
• Google Sheets (Append Row): عملیات API استخراج شده را به یک Google Sheet اضافه می‌کند.
• Google Sheets (Extract Result / Extract Error): وضعیت سرویس را در Google Sheets بر اساس نتیجه استخراج به‌روزرسانی می‌کند.
• Wait (Wait1): تاخیری را برای تنظیم سرعت معرفی می‌کند.

موارد مرزی و انواع شکست (Edge Cases & Failure Types):

• عدم یافتن اسناد مرتبط در فروشگاه برداری.
• شکست LLM در استخراج داده‌های معتبر.
• مشکلات مجوز یا سهمیه Google Sheets.
• خطاهای پرس‌وجو یا بارگذاری فروشگاه برداری.
• شکست در اجرای گردش کار فرعی.

---

۴. مرحله ۳ - تولید (Generation)

این مرحله نهایی طرحواره API را تولید و ذخیره می‌کند.

گره‌ها (Nodes):

• Google Sheets (Get All Generate): سرویس‌هایی را که تحقیق و استخراج آن‌ها تکمیل شده و آماده تولید طرحواره هستند، بازیابی می‌کند.
• If (All Generate Done?): بررسی می‌کند که آیا سرویس دیگری برای تولید باقی مانده است یا خیر.
• SplitInBatches (For Each Generate…): هر سرویس را به صورت جداگانه پردازش می‌کند.
• Google Sheets (Generate Pending): وضعیت سرویس را در Google Sheets به "در انتظار تولید" (pending) به‌روزرسانی می‌کند.
• Set (Generate Event): داده‌های رویداد را برای گردش کار فرعی تولید آماده می‌کند.
• Execute Workflow (Generate): یک گردش کار فرعی را برای تولید طرحواره برای یک سرویس واحد اجرا می‌کند.
• Google Sheets (Get API Operations): تمام عملیات API استخراج شده برای سرویس را می‌خواند.
• Code (Contruct JSON Schema): عملیات API را جمع‌آوری می‌کند، آن‌ها را بر اساس منبع گروه‌بندی می‌کند و آن‌ها را در یک طرحواره JSON سفارشی قالب‌بندی می‌کند.
• Set (Set Upload Fields): نام فایل را آماده کرده و طرحواره JSON را برای آپلود رشته‌ای می‌کند.
• Google Drive Upload (Upload to Drive): فایل طرحواره JSON تولید شده را در پوشه مشخص شده Google Drive آپلود می‌کند.
• Set (Response OK2): وضعیت موفقیت را تنظیم می‌کند.
• Google Sheets (Generate Result / Generate Error): وضعیت نهایی و نام فایل طرحواره تولید شده را در Google Sheet به‌روزرسانی می‌کند.
• Wait (Wait2): تاخیری را برای تنظیم سرعت معرفی می‌کند.

موارد مرزی و انواع شکست (Edge Cases & Failure Types):

• خطاهای خواندن/نوشتن یا فیلتر کردن Google Sheets.
• مشکلات مجوز یا سهمیه آپلود Google Drive.
• خطاها در گره Code هنگام ساخت طرحواره JSON.
• خطاها یا مهلت زمانی گردش کار فرعی.

---

خلاصه نودها

---

توجه: این گردش کار به سرویس‌های خارجی مانند Apify برای خراشیدن وب و سرویس‌های گوگل (Sheets, Drive) برای مدیریت داده‌ها متکی است. اطمینان حاصل کنید که احراز هویت و مجوزهای مناسب برای این سرویس‌ها پیکربندی شده‌اند. نودهای LLM از Gemini استفاده می‌کنند که نیاز به کلیدهای API و راه‌اندازی مناسب دارد.