اتصال Google Sheets و ابزارهای گوگل
برای اتصال n8n آنلاین به Google Sheets با OAuth2، ابتدا دامنهٔ شخصی و envهای آدرس عمومی را آماده کنید؛ سپس برنامهٔ OAuth خود را در Google Cloud بسازید. سرویس n8n روی چابکان یا کلودیوا، نسخهٔ self-hosted محسوب می‌شود؛ ورود مدیریت‌شدهٔ مخصوص n8n Cloud را فرض نکنید. راهنمای OAuth گوگل در n8n
چرا دامنهٔ شخصی؟
دامنه‌ای مثل n8n.example.com آدرس ثابتی برای بازگشت مرورگر از گوگل می‌دهد و مالکیت دامنه را برای تنظیمات یا تأیید برنامه در اختیار شما می‌گذارد. دامنهٔ پیش‌فرض مشترک ارائه‌دهنده لزوماً تحت مالکیت شما نیست؛ برای تأیید برند OAuth ممکن است نتوانید مالکیت دامنهٔ اصلی آن را اثبات کنید. الزامات دامنه و تأیید برند گوگل
دامنهٔ شخصی شرط تمام اتصال‌های گوگل نیست. OAuth محلی می‌تواند از localhost استفاده کند و روش Service Account برای nodeهای سازگار، بازگشت مرورگر OAuth ندارد. این راهنما مسیر پیشنهادی OAuth برای n8n آنلاین با HTTPS و دامنهٔ تحت کنترل شما را توضیح می‌دهد. روش‌های OAuth در n8n، Service Account
۱. آدرس n8n را آماده کنید
در پنل برنامه‌های آماده ← سرویس n8n ← تنظیمات ← متغیرهای محیطی، N8N_HOST، N8N_PROTOCOL، N8N_EDITOR_BASE_URL و متغیر webhook مناسب نسخه را مطابق راهنمای دامنه تنظیم و ذخیره کنید. بعد از آماده‌شدن، از دامنهٔ شخصی وارد editor شوید.
در n8n یک node Google Sheets اضافه و از بخش Credential، credential جدید Google Sheets OAuth2 API بسازید. OAuth Redirect URL نمایش‌داده‌شده را کپی کنید؛ نمونه:
https://n8n.example.com/rest/oauth2-credential/callback
اگر URL هنوز دامنهٔ پیش‌فرض، localhost، HTTP یا پورت داخلی دارد، ابتدا تنظیمات n8n را اصلاح کنید. callback را به‌صورت دستی حدس نزنید.
۲. پروژه و APIهای گوگل را آماده کنید
در Google Cloud Console، یک پروژه ایجاد یا پروژهٔ موردنظر را انتخاب کنید. از APIs & Services ← Library این APIها را فعال کنید:
- Google Sheets API برای خواندن و تغییر spreadsheet.
- Google Drive API برای قابلیت‌های مرتبط با فایل و انتخاب سند در اتصال n8n.
راهنمای n8n برای اتصال Sheets فعال‌بودن هر دو را ذکر می‌کند. APIهای موردنیاز n8n
۳. صفحهٔ رضایت و دامنهٔ مجاز
از Google Auth Platform یا APIs & Services ← OAuth consent screen تنظیمات برنامه را باز کنید:
- در Branding نام برنامه، ایمیل پشتیبانی و اطلاعات لازم را وارد کنید.
- در Audience برای استفادهٔ شخصی با حساب معمولی گوگل، External را انتخاب و در حالت Testing، ایمیل خود را به Test users اضافه کنید. Internal مخصوص کاربران سازمان Google Workspace واجد شرایط است.
- در Authorized domains دامنهٔ قابل ثبت، مثلاً
example.com، را وارد کنید؛ این فیلد URL کامل callback نیست. برای تأیید مالکیت، در صورت درخواست گوگل، از روش رسمی Search Console استفاده کنید. - در Data Access فقط scopeهای لازم برای کاری که node انجام می‌دهد را تعریف کنید. برای انتشار عمومی، الزامات تأیید برنامه و scopeها را بررسی کنید؛ دامنهٔ شخصی به‌تنهایی تأیید گوگل را انجام نمی‌دهد.
مراحل صفحهٔ رضایت و scopeها در راهنمای گوگل و قواعد مالکیت دامنه در راهنمای تأیید برند آمده‌اند.
۴. Client ID و callback را ثبت کنید
از Google Auth Platform ← Clients یا APIs & Services ← Credentials، یک OAuth client ID از نوع Web application بسازید.
در Authorized redirect URIs، همان OAuth Redirect URL کپی‌شده از n8n را عیناً ثبت کنید. پروتکل، میزبان، پورت در صورت وجود، مسیر و اسلش انتهایی باید با آدرس ارسالی یکسان باشند. ثبت فقط https://n8n.example.com کافی نیست؛ مسیر callback هم لازم است. فیلد Authorized JavaScript origins جای Redirect URI را نمی‌گیرد. قواعد OAuth برنامهٔ وب گوگل
Client ID و Client Secret را در credential گوگل داخل n8n وارد کنید، نه در متغیرهای دامنه یا node عمومی. سپس Sign in with Google را بزنید و دسترسی‌های درخواست‌شده را بررسی کنید. در حالت Testing، با همان حسابی وارد شوید که در Test users اضافه کرده‌اید. credential را ذخیره کنید.
۵. یک خواندن واقعی را آزمایش کنید
یک spreadsheet آزمای شی در اختیار حساب متصل بسازید و در سطر اول ستون‌هایی مثل title و summary قرار دهید. در Google Sheets node، credential ساخته‌شده، Document و Sheet را انتخاب و عملیات خواندن مانند Get Row(s) را اجرا کنید. اگر فهرست سند بارگذاری نشد، در گزینه‌های موجود node، ID یا URL سند را وارد کنید و دسترسی حساب به همان فایل را بررسی کنید. مرجع Google Sheets node
موفقیت ورود OAuth به‌تنهایی دسترسی به هر فایل را ثابت نمی‌کند؛ باید خروجی واقعی node را ببینید. بعداً می‌توانید داده را به هوش مصنوعی چابکان بدهید و خلاصه را با عملیات Append Row در sheet آزمایشی ثبت کنید. ابتدا روی فایل آزمایشی کار کنید تا retry یا نگاشت اشتباه، دادهٔ اصلی را تکرار یا تغییر ندهد.
خطاهای رایج
| خطا | بررسی |
|---|---|
redirect_uri_mismatch | callback نمایش‌داده‌شده در n8n را با Authorized redirect URIs همان OAuth Client تطبیق دهید؛ پس از تغییر دامنه، هر دو سمت را به‌روز کنید. |
access_denied در حالت Testing | حساب واردشده را در Test users بررسی کنید؛ ممکن است سیاست Google Workspace نیز دسترسی را محدود کند. |
invalid_client | Client ID و Client Secret همان پروژه و client را بدون فاصلهٔ اضافی وارد کنید. |
| ورود موفق ولی سند پیدا نمی‌شود | حساب متصل، ID سند، مجوز فایل و فعال‌بودن Sheets/Drive API را بررسی کنید. |
| timeout یا خطای شبکه | اتصال خروجی سرور n8n به گوگل را بررسی کنید؛ دامنهٔ شخصی محدودیت IP یا شبکه را رفع نمی‌کند. برای مقصدهای محدود از ایران، انتخاب موقعیت کلودیوا را بررسی کنید. |
اگر پس از تغییر دامنه اتصال قبلی کار نمی‌کند، callback گوگل را اصلاح و credential را دوباره متصل کنید. برای Gmail، Calendar یا Drive، منطق دامنه و OAuth مشابه است، ولی API، scope و credential مخصوص همان node را باید انتخاب کنید.