آموزش جامع n8n (قسمت دوم): درک زبان اینترنت با API و Webhook

در مقاله قبل با اتوماسیون ها و مزیت های آن ها آشنا شدیم اما برای اینکه بتوانیم “ورک‌فلوهای” (Workflows) واقعی و قدرتمند بسازیم، باید مفاهیم API و Webhook را به خوبی بدانیم و زبان مشترک همه اپلیکیشن ها را یاد بگیریم . در ادامه این دو مفهوم بسیار مهم را تعریف خواهیم کرد. این مفاهیم پایه و اساس اتوماسیون ها و طراحی ورک فلو های n8n هستند.

API چیست؟ (رابط برنامه‌نویسی اپلیکیشن)

API مخفف Application Programming Interface است.یک API در واقع رابط و پل بین دو نزم افزار است و استفاده از ان کمک می‌کند تا نرم افزار ها به راحتی با هم اطلاعات رد و بدل کنند. API ها قواین مخصوص به خود را دارند و با استفاده از این قواینارتباط بین نرم افزار ها را ممکن می‌کند. در واقع یک API سرویس‌هایی را در اختیار ما قرار می‌دهد تا بتوانیم از آن‌ها استفاده کنیم. مثلاً اگر نرم افزاری از API گوگل شیت استفاده کند، می‌تواند  داده‌های موجود در یک فایل اکسل آنلاین را بخوانید یا تغییر دهید.

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

چرا به API نیاز داریم؟

تصور کنید اگر هر بار که به رستوران می‌رفتید، مجبور بودید خودتان به آشپزخانه بروید، مواد اولیه را پیدا کنید و غذایتان را بپزید! چقدر پیچیده و سخت می‌شد؟ وجود گارسون این پیچیدگی را از بین می‌برد. در دنیای نرم‌افزار هم همینطور است. اگر قرار بود برای خواندن یک داده ساده از گوگل، مستقیماً به سرورهای گوگل وصل شوید و کدهای پیچیده بنویسید، کار بسیار دشوار می‌شد. API به شما اجازه می‌دهد بدون درگیر شدن با پیچیدگی‌های پشت صحنه، فقط درخواست خود را ارسال کنید و نتیجه را بگیرید.
برای اینکه بدانید چه چیزهایی می‌توانید سفارش دهید، نیاز به مستندات (Documentation) دارید. در مثال رستوران، مستندات همان منو است که لیست غذاها و قیمت‌ها را به شما نشان می‌دهد.

آناتومی یک درخواست (HTTP Request)

حالا که فهمیدیم API چیست، بیایید ببینیم وقتی یک درخواست (Request) ارسال می‌کنیم، چه اتفاقی می‌افتد. یک درخواست HTTP از چهار بخش اصلی تشکیل شده است:
1. URL
2. متد (Method)
3. هدر (Header)
4. بدنه (Body)

در ادامه هر 4 مورد ذکر شده را بررسی می‌کنیم :

۱. آدرس یا URL

URL همان آدرس منحصر‌به‌فرد یک منبع در اینترنت است. این منبع می‌تواند یک صفحه وب، یک تصویر، یک PDF یا تکه‌ای داده باشد. یک URL شامل بخش‌های اجباری مثل هاست (Host) و مسیر (Path) و بخش‌های اختیاری مثل پورت و پارامترهای کوئری (Query Parameters) است. نکته مهم این است که پارامترهای کوئری همیشه بعد از علامت سوال (?) می‌آیند.

۲. متد (Method): چه کاری می‌خواهید انجام دهید؟

متد به سرور می‌گوید که قصد ما از این درخواست چیست. متدها معمولاً به صورت “فعل” هستند که نیت ما را شفاف می‌کنند. دو متد اصلی که بیشترین سروکار را با آن‌ها خواهید داشت عبارتند از:
• GET: برای دریافت اطلاعات. (مثلاً خواندن ردیف‌های یک گوگل شیت).
• POST: برای ارسال اطلاعات. (مثلاً ثبت یک فرم جدید).
البته متدهای دیگری مثل DELETE (حذف)، PUT و PATCH (ویرایش) هم وجود دارند که کمتر رایج هستند.

۳. هدر (Header): اطلاعات تکمیلی

هدر مثل اطلاعات زمینه‌ای است که به گارسون می‌دهید. مثلاً به او می‌گویید “من به زبان انگلیسی صحبت می‌کنم”. در دنیای وب، هدر شامل اطلاعاتی مثل موقعیت مکانی، نوع دستگاه شما یا فرمت درخواستی است. یک مثال رایج در هدر: Accept: application/json. این به سرور می‌گوید: “لطفاً جواب من را به فرمت JSON بده”.

۴. بدنه (Body): محموله اصلی

بدنه اختیاری است و معمولاً فقط در درخواست‌های POST (ارسال اطلاعات) وجود دارد. اینجا جایی است که داده‌های اصلی قرار می‌گیرند. مثلاً اگر کاربری در سایت شما فرمی پر کرده است، نام، ایمیل و پیام او در بخش “Body” قرار می‌گیرد تا به سرور ارسال شود.

مبحث مهم: امنیت و احراز هویت (Credentials)

آیا هر کسی می‌تواند وارد آشپزخانه شود و دستور دهد؟ قطعاً خیر. شما باید نشان دهید که مشتری هستید یا پول پرداخت کرده‌اید. در API هم اگر هر کسی بتواند داده‌های گوگل شیت شما را بخواند یا پیامی در اسلک شما بفرستد، فاجعه امنیتی رخ می‌دهد.
برای جلوگیری از این کار، ما از Credentials استفاده می‌کنیم. این کار معمولاً به دو روش انجام می‌شود:
1. API Key: مثل یک رمز عبور طولانی که در هدر یا URL ارسال می‌شود.
2. OAuth: همان دکمه‌های “Sign in with Google” که پنجره‌ای باز می‌شود و شما تایید می‌کنید. این روش امن‌تر و رایج‌تر است.

پاسخ سرور (Response)

وقتی شما درخواست (Request) را فرستادید، اپلیکیشن پردازش را انجام می‌دهد و یک پاسخ (Response) برمی‌گرداند. یک پاسخ استاندارد شامل سه بخش است: کد وضعیت، هدر و بدنه.

کدهای وضعیت (Status Codes)

این کدها یک عدد سه رقمی هستند که به سرعت به شما می‌گویند آیا کار با موفقیت انجام شد یا خیر. یک راه ساده برای حفظ کردن آن‌ها وجود دارد،:
• سری ۲۰۰ (مثل 200 OK): تبریک می‌گویم! همه چیز عالی پیش رفت. درخواست شما موفق بود.
• سری ۴۰۰ (مثل 404 یا 401): شما اشتباه کردید!
◦ 401 Unauthorized: یعنی کلید ورود (Credential) را ندادید یا اشتباه است.
◦ 404 Not Found: یعنی آدرس (URL) اشتباه است و چیزی پیدا نشد.
• سری ۵۰۰ (مثل 500 Server Error): سرور خرابکاری کرد! مشکل از سمت شما نیست، سرور داخلی اپلیکیشن دچار مشکل شده است.
بنابراین، اگر کد با ۲ شروع شد، خوشحال باشید. اگر با ۴ شروع شد، درخواست خود را چک کنید. اگر با ۵ شروع شد، بعداً تلاش کنید.
بدنه پاسخ (Response Body)
این همان چیزی است که منتظرش بودید. داده‌ای که درخواست کرده بودید (مثلاً لیست مشتریان) در این بخش قرار دارد و معمولاً به فرمت JSON است.

وب‌هوک (Webhook)

تا اینجا یاد گرفتیم که چطور با API درخواست بفرستیم. اما گاهی اوقات ما منتظر یک اتفاق هستیم. اینجا مفهوم Webhook یا همان “API معکوس” وارد می‌شود.
تمثیل زنگ درب
تصور کنید منتظر دوستانتان هستید که به خانه شما بیایند. دو راه دارید:
1. Polling (سرک کشیدن): هر چند دقیقه یکبار بروید دم در، در را باز کنید و ببینید کسی آمده یا نه. این کار خسته‌کننده است و منابع زیادی مصرف می‌کند.
2. Webhook (زنگ درب): راحت روی مبل می‌نشینید و منتظر می‌مانید تا زنگ در به صدا دربیاید. زنگ در به شما “خبر” می‌دهد که رویداد اتفاق افتاد.

فرض کنید می‌خواهید هر وقت خریدی در سایت (مثلاً از طریق Stripe) انجام شد، باخبر شوید.
• در روش Polling، شما باید هر ۵ دقیقه از Stripe بپرسید: “آیا خرید جدیدی هست؟”. اکثر اوقات پاسخ منفی است.
• در روش Webhook، شما یک آدرس URL به Stripe می‌دهید. هر وقت خریدی انجام شد، Stripe خودش آن اطلاعات را به آدرس شما (به n8n) می‌فرستد.
وب‌هوک‌ها برای شروع اتوماسیون‌ها (Trigger) فوق‌العاده هستند چون “بلادرنگ” (Real-time) عمل می‌کنند و نیازی به چک کردن مداوم ندارند. برای استفاده از آن‌ها در n8n، شما از نودِ Webhook استفاده می‌کنید که یک URL اختصاصی به شما می‌دهد تا در سرویس مورد نظرتان (مثل تلگرام، فرم‌سازها یا درگاه پرداخت) ثبت کنید.

جمع‌بندی
در این مقاله که بر اساس قسمت دوم دوره n8n نوشته شد، ما زبان اینترنت را یاد گرفتیم. فهمیدیم که:
• API مثل یک گارسون است که درخواست ما را به آشپزخانه (اپلیکیشن) می‌برد.
• HTTP Request شامل URL (آدرس)، Method (فعل)، Header (زمینه) و Body (داده) است.
• Status Codes به ما می‌گویند درخواست موفق بوده (200) یا شکست خورده (400/500).
• Webhook مثل زنگ درب است که به جای پرسش مداوم، ما را از رویدادها باخبر می‌کند.

سوالات متداول (FAQ)