دليل · gmail api

كيف ينفّذ فريق المنتج Gmail API بأمان؟

نفّذ Gmail API بوصفه وصولًا مفوَّضًا إلى صندوق Gmail محدد، لا بوصفه بيانات اعتماد عامة لتسليم البريد. اختر أصغر نطاق OAuth يدعم الميزة، واحمِ حالة التفويض ورموز التحديث (refresh tokens)، وأبقِ كل صندوق بريد محصورًا بمستأجره. ابنِ الرسائل بمكتبة ناضجة لرسائل الإنترنت، وسجّل معرّف رسالة Gmail المُعاد، وزامن التغييرات عبر Pub/Sub مع سجلات history. تعامل مع انتحال هوية حساب الخدمة على أنه قرار لمسؤول Workspace. وأخيرًا، أبقِ قبول API والتسليم إلى الخادم المستقبِل والوصول إلى صندوق الوارد نتائج منفصلة.

اختر نموذج صندوق البريد قبل كتابة الشيفرة

يعمل Gmail API على صندوق Gmail الخاص بمستخدم. وهو مناسب عندما يحتاج المنتج إلى قراءة ذلك الصندوق أو تنظيم تصنيفاته وسلاسل رسائله أو إنشاء مسودات أو الإرسال باسم المستخدم المفوِّض أو مزامنة تغييرات الصندوق. هذه الصلاحية أوسع بكثير من استدعاء واجهة API لبريد التطبيقات من نطاق منتج موثَّق. ابدأ بتسمية مهمة صندوق البريد بدقة والجهة التي تمنح الوصول. يستخدم المنتج الموجَّه للمستخدمين عادةً موافقة OAuth لكل حساب Google متصل. أما أتمتة داخلية في Google Workspace فقد تستخدم بدلًا من ذلك تفويضًا على مستوى النطاق (domain-wide delegation) يعتمده المسؤول. وإذا كان المطلوب فقط إرسال الإيصالات أو روابط التحقق أو التنبيهات أو غيرها من الرسائل التي يطلقها المنتج من نطاق تتحكم فيه الشركة، فتجنّب الوصول إلى صندوق البريد تمامًا وقيّم واجهة API للبريد المعاملاتي. يقلل هذا القرار المعماري الوصول غير الضروري قبل أن يضطر أي ضابط أمني أو شاشة موافقة إلى تعويضه.

امنح أضيق نطاق عملي

اضبط عميل OAuth للنوع الصحيح من التطبيقات، واستخدم URI إعادة توجيه مسجلًا بالضبط، واربط استجابة التفويض بجلسة المتصفح التي بدأتها بقيمة state لا يمكن التنبؤ بها. اطلب الوصول في السياق، عندما يفعّل المستخدم الميزة التي تحتاجه. بالنسبة إلى تكامل للإرسال فقط، فإن `https://www.googleapis.com/auth/gmail.send` أضيق من النطاقات التي تقرأ صندوق البريد أو تعدّله. تصنّف Google النطاق `gmail.send` على أنه حساس، بينما تُعد نطاقات مثل `gmail.readonly` و`gmail.compose` و`gmail.modify` مقيَّدة. قد يتطلب التطبيق العام الذي يستخدم وصولًا حساسًا أو مقيَّدًا التحقق من OAuth، وقد يؤدي تخزين بيانات النطاقات المقيَّدة أو نقلها على الخادم إلى متطلبات تقييم أمني إضافية. اطلب الوصول دون اتصال (offline access) فقط عندما يكون العمل في الخلفية ضروريًا فعلًا. شفّر رموز التحديث، واربط كل رمز بمستأجر داخلي واحد وبمعرّف Google (subject) واحد، ولا تكشفه أبدًا لشيفرة المتصفح أو السجلات، ووفّر مسار فصل (disconnect) مختبَرًا يحذف بيانات الاعتماد المحلية ويوقف المعالجة في الخلفية.

افهم حسابات الخدمة والتفويض على مستوى النطاق

حساب الخدمة هوية تطبيق، وليس صندوق Gmail جاهزًا للاستخدام. فهو بمفرده لا يحصل على حق الوصول إلى رسائل الموظفين. وبالنسبة إلى بيانات مستخدمي Google Workspace، يجب أن يصرّح مسؤول خارق (super administrator) صراحةً بمعرّف العميل الرقمي لحساب الخدمة وبقائمة دقيقة من نطاقات OAuth عبر التفويض على مستوى النطاق. ثم يطلب التطبيق بيانات اعتماد مفوَّضة لمستخدم مسمّى، وتعمل كل استدعاءات API بصلاحيات ذلك المستخدم ضمن النطاقات المصرَّح بها. أبقِ الموضوع المنتحَل (subject) صريحًا في بيانات المهام وسجلات التدقيق حتى لا يتمكن عامل في الخلفية من تبديل صناديق البريد بصمت. استخدم حسابات خدمة منفصلة لأعباء العمل المختلفة جوهريًا، وتجنّب المفاتيح الخاصة القابلة للتنزيل عندما تستطيع بيئة التشغيل استخدام بيانات اعتماد مُدارة، وراجع منح التفويض على مستوى النطاق وفق جدول. لا تملك حسابات Gmail الاستهلاكية مسؤول Workspace يستطيع منح هذا التفويض على مستوى المؤسسة، لذلك استخدم موافقة OAuth من المستخدم لتلك الحسابات.

أرسل الرسائل دون فقدان التحكم أو قابلية التدقيق

يقبل Gmail رسالة بريد إنترنت كاملة في الحقل `raw`، مشفّرة بـ base64url، عبر `users.messages.send`؛ ويمكن للمنتج أيضًا إنشاء مسودة وإرسالها لاحقًا. استخدم مكتبة رسائل مصانة لتوليد بنية From وTo وCc وBcc وSubject وDate وMessage-ID والنص وHTML والمرفقات بدلًا من ربط أسطر الترويسات يدويًا. تحقق من المستلِمين والمحتوى قبل الترميز، وارفض حقن الترويسات (header injection)، وحدد حدود حجم صريحة. اجعل إجراء المنتج غير مكرَّر (idempotent) قبل استدعاء Gmail: خزّن مفتاح حدث ثابتًا للتطبيق وموضوع صندوق البريد المقصود وحالة محاولة الإرسال. وبعد استجابة ناجحة، خزّن معرّف رسالة Gmail ومعرّف السلسلة المُعادَين مع ذلك الحدث. وإذا انتهت مهلة العميل بعد إرسال الطلب، فطابِق حالة صندوق البريد قبل إعادة المحاولة لأن الرسالة ربما قُبلت بالفعل. قد تنتج إعادة المحاولة العمياء رسالة مكررة حتى لو ضاعت الاستجابة الأصلية. استخدم إنشاء المسودة مع المراجعة البشرية عندما يتطلب المحتوى أو المستلِمون موافقة.

زامن تغييرات صندوق البريد بسجلات history

في تكامل صندوق البريد على الخادم، تنشر عملية watch في Gmail إشارات التغيير عبر Google Cloud Pub/Sub. الإشعار مجرد طلب للمزامنة وليس حمولة رسالة كاملة. خزّن history ID الحالي وموعد الانتهاء من استجابة watch، وأقرّ بالإشعارات بسرعة، واستدعِ `users.history.list` انطلاقًا من آخر history ID تم تثبيته بنجاح لاكتشاف تغييرات الرسائل والتصنيفات. اجلب فقط الرسائل التي تحتاجها الميزة، ثم قدّم نقطة التحقق بعد نجاح الكتابات المحلية. قد تتأخر الإشعارات أو تتكرر، لذلك اجعل معالجة الرسائل وhistory غير مكرَّرة (idempotent). يشترط Gmail تجديد مراقبة صندوق البريد مرة كل سبعة أيام على الأقل ويوصي بالتجديد يوميًا؛ جدول التجديد قبل الانتهاء بوقت كافٍ ونبّه عند الإخفاق. وإذا كان history ID المخزَّن خارج النطاق المتاح في Gmail، تعيد API الخطأ HTTP 404. تعامل مع ذلك على أنه مسار تعافٍ معرَّف: أجرِ مزامنة كاملة خاضعة للتحكم، وأنشئ نقطة تحقق جديدة، واستأنف المعالجة التزايدية بدلًا من إعادة محاولة history ID غير الصالح إلى ما لا نهاية.

استخدم سير عمل تنفيذ وتحقق على مراحل

أولًا، وثّق هل تُرسل الميزة البريد أو تقرؤه أو تعدّله أو تراقبه، واربط كل عملية بأدنى نطاق OAuth لها. ثانيًا، أنشئ مشاريع Google Cloud أو عملاء OAuth منفصلة للتطوير والإنتاج، مع URIs إعادة توجيه دقيقة ومالكين مسمّين لبيانات الاعتماد. ثالثًا، نفّذ التفويض مع التحقق من state، والوصول دون اتصال عند الحاجة فقط، وتخزين رموز مشفّر، وإلغاء الرموز، وفحوصات وصول على مستوى المستأجر. رابعًا، اختبر بصناديق بريد خاضعة للتحكم: اتصل، وحدّث رمز وصول منتهي الصلاحية، وأبطل الموافقة، وأعد الاتصال، وأرسل مرة واحدة، وحاكِ مهلة ملتبسة، وتأكد من منع التكرار. خامسًا، إذا كنت تستقبل التغييرات، فوفّر أذونات Pub/Sub وابدأ watch وعالج history تزايديًا وافرض تعافيًا من نقطة تحقق قديمة وتحقق من تجديد watch. سادسًا، أضف طوابير عمل لكل مستخدم وتراجعًا أُسّيًا محدودًا (bounded exponential backoff) وتصنيفًا منظَّمًا للأخطاء وسجلات تدقيق تستثني متون الرسائل والرموز افتراضيًا. وقبل الإطلاق، أكمل أي تحقق مطلوب من Google ومراجعة أمنية، وانشر إفصاحات دقيقة لاستخدام البيانات، وتمرّن على تدوير بيانات الاعتماد وحذف بيانات المستخدم.

خطّط للحصص وإعادة المحاولة والفشل الجزئي

يقيس Gmail استخدام API بوحدات الحصة، وليس بعدد الطلبات فقط. تسرد صفحة الحصص في Google 1,200,000 وحدة في الدقيقة لكل مشروع و6,000 وحدة في الدقيقة لكل مستخدم ولكل مشروع. وتسرد `messages.send` و`drafts.send` و`watch` بواقع 100 وحدة لكل منها، وحدًا قدره 500 مستلِم لكل رسالة. ما زالت حدود الإرسال المنفصلة للمستخدم في Gmail تنطبق على عملاء API والويب وSMTP. تعامل مع وحدة تحكم Cloud والوثائق الحالية بوصفها مدخلات لإعداد وقت التشغيل بدلًا من ترميز الحدود المنشورة ضمن منطق الأعمال. نفّذ العمل تسلسليًا أو ضعه في طابور عادل لكل صندوق بريد، وحدّ التزامن، وأعد محاولة الاستجابات العابرة فقط باستخدام تراجع أُسّي مع ارتعاش وموعد نهائي محدود. لا تعِد محاولة أخطاء التفويض أو السياسة أو المستلِم غير الصالح أو الرسالة المشوّهة كما لو كانت مشكلات سعة. تقلل الدفعة متعددة الأجزاء عبء الاتصال، لكن كل استدعاء داخلي يستهلك الحصة أيضًا ويمكن أن يفشل بشكل مستقل.

أبقِ القبول والتسليم والوصول إلى صندوق الوارد منفصلة

يعني نجاح استدعاء `messages.send` أن Gmail قبل طلب API المصرّح به وأعاد مورد Message. ولا يثبت أن خادم بريد كل مستلِم قبل الرسالة، ولا يستطيع تحديد المكان الذي صنّف فيه النظام المستقبِل الرسالة. يعني التسليم إلى الخادم المستقبِل أن النظام الوجهة قبل مسؤولية SMTP. أما الوصول إلى صندوق الوارد فهو نتيجة ترشيح لاحقة، مثل الوارد الأساسي أو العروض الترويجية أو العزل أو البريد المزعج. لذلك فإن واجهة API لصندوق بريد Gmail ليست بديلًا عن تدفق أحداث المزوّد عندما يحتاج المنتج إلى قياسات التسليم أو الارتداد أو الشكاوى للبريد المعاملاتي. احتفظ بمعرّف رسالة Gmail للمطابقة، لكن صِف الحالة الظاهرة للمستخدم بدقة على أنها «أُرسلت» أو «قبلها Gmail» ما لم يدعم التسليم دليل منفصل. تؤثر المصادقة والمستلِمون المتوقعون وجودة المحتوى وسلوك الإرسال وسياسة الوجهة كلها في المعالجة اللاحقة. ولا تستطيع استجابة API تحديد المجلد النهائي للمستلِم أو الوعد به.

اعرف متى تناسب واجهة API للبريد المعاملاتي مهمة مختلفة

استخدم Gmail API عندما يحتاج المنتج إلى وصول مخوّل إلى صندوق بريد Gmail لشخص أو مؤسسة، بما في ذلك سلاسل الرسائل والتصنيفات والمسودات أو مزامنة صندوق البريد. تناسب واجهة API للبريد المعاملاتي بنية مختلفة: رسائل يطلقها التطبيق وتُرسل من نطاقات تتحكم فيها المؤسسة، من دون سلطة مفوّضة لقراءة صندوق بريد Gmail الخاص بالمستخدم. يمكن للمنتج استخدام كلا النوعين من الأنظمة عندما تكون الحدود صريحة، مثل Gmail OAuth لقراءة صندوق البريد المتصل لوكيل دعم ومزوّد معامَلاتي موثَّق بشكل منفصل لإرسال إيصالات المنتج. أبقِ بيانات الاعتماد والموافقة ومخازن الرسائل وسياسات إعادة المحاولة وسجلات التدقيق منفصلة كي لا تتسرب سلطة صندوق البريد إلى الإرسال على مستوى التطبيق ولكي لا تتمكن بيانات اعتماد معامَلاتية من قراءة Gmail للمستخدم.

الأسئلة الشائعة

هل يستطيع حساب الخدمة الوصول إلى أي صندوق Gmail؟

لا. لا يحصل حساب الخدمة تلقائيًا على حق الوصول إلى بيانات مستخدمي Gmail. يجب أن يمنح مسؤول خارق في Google Workspace تفويضًا على مستوى النطاق لمعرّف العميل الرقمي الخاص به وللنطاقات المعتمدة، وبعدها ينتحل التطبيق هوية مستخدم في تلك المؤسسة صراحةً. أما حسابات Gmail الاستهلاكية فاستخدم لها موافقة OAuth من المستخدم.

أي نطاق OAuth ينبغي أن يطلبه تكامل Gmail للإرسال فقط؟

ابدأ بتقييم `https://www.googleapis.com/auth/gmail.send`، الذي يسمح بالإرسال نيابةً عن المستخدم دون منح صلاحية قراءة عامة لصندوق البريد. تأكد من أنه لا يوجد متطلب في المنتج يحتاج فعلًا إلى المسودات أو قراءة الرسائل أو التصنيفات أو التعديل قبل طلب نطاق (scope) أوسع، وضع في حسابك قواعد التحقق من Google الخاصة بالنطاقات الحساسة.

هل يعني نجاح إرسال Gmail API أن الرسالة سُلِّمت؟

لا. إنه يؤكد أن Gmail قبل عملية API المصرّح بها وأعاد سجل رسالة. أما قبول الخادم المستقبِل والوصول إلى صندوق الوارد فهما حالتان لاحقتان منفصلتان. لا تصف الرسالة بأنها سُلِّمت ولا تعد بالوصول إلى صندوق الوارد ما لم تدعم ذلك إشارة أخرى موثوقة.

هل تحتوي إشعارات push في Gmail على الرسالة الجديدة كاملة؟

لا. يشير إشعار Pub/Sub إلى أن حالة صندوق البريد تغيّرت ويتضمن معلومات تُستخدم لمواصلة المزامنة. ينبغي للتطبيق أن يستعلم عن history في Gmail بدءًا من history ID المحفوظ، وأن يجلب بيانات الرسالة المطلوبة، وأن يعالج بشكل غير مكرَّر (idempotent)، ثم يقدّم نقطة التحقق.

كم مرة يجب تجديد مراقبة صندوق Gmail (watch)؟

تشترط Google استدعاء `watch` مرة كل سبعة أيام على الأقل وتوصي بالتجديد يوميًا. خزّن موعد الانتهاء المُعاد، وجدّد قبله، وراقب الإخفاقات، وأبقِ مهمة مزامنة احتياطية حتى لا يؤدي تجديد فائت بصمت إلى فجوة بيانات غير محدودة.

متى ينبغي للفريق استخدام واجهة API للبريد المعاملاتي بدلًا من Gmail API؟

استخدم واجهة API للبريد المعاملاتي عندما تكون المهمة بريدًا يطلقه التطبيق من نطاقات تتحكم فيها المؤسسة ولا تحتاج أي ميزة إلى الوصول إلى صندوق Gmail الخاص بشخص ما. واستخدم Gmail API عندما يحتاج المنتج تحديدًا إلى رسائل صندوق بريد مفوَّضة أو سلاسل رسائل أو تصنيفات أو مسودات أو إعدادات أو صلاحية الإرسال باسم آخر (send-as).

المصادر

تابع التعلّم

دليل تنفيذ واجهة API للبريد الإلكتروني لفرق المنتجصمّم تكامل واجهة API للبريد الإلكتروني آمنًا مع نطاقات موثَّقة وعمليات إرسال في طابور ومعرّفات ثابتة وإعادة محاولات خاضعة للتحكم وأحداث تسليم ومنع وعزل المستأجرين.