كيفية إنشاء عميل OAuth

إصدار API 2026-10-affable-towhee

قبل أن تضغط «إنشاء عميل» في صفحة عمليات التكامل، حدّد ثلاثة أمور: ما الذي يُسمح للعميل بفعله، وأي عملية تحتفظ بسرّه، ومن يدفع ثمن استدعاءاته. يضع دليل المصادقة القواعد، وتطبّقها هذه الصفحة على شركتين خياليتين، Luba وFarducks.

Luba: الـ Dive Deck

تشغّل Luba غواصات ذاتية القيادة لخدمة نقل ومشاركة رحلات. ويعرض Dive Deck الخاص بها على شاشة المقصورة لكل راكب عبارةً من الغوصة، باللغة التي يتعلّمها، بينما يراقب فريق العمليات في Luba مقدار ما تبقّى من الحصة.

تنشئ Luba عميلًا واحدًا، Luba Dive Deck، مسموحًا له بـ«توليد المفردات» (vocab:generate) و«قراءة الاستخدام» (usage:read)، ويُفوتَر على «الحصة المضمّنة في خطتك» (allowance). تتشاركه عمليتان، وتطلب كل منهما عند الاستبدال النطاق الذي تحتاجه فقط. الاستبدال الذي يغفل scope يحصل على كل النطاقات المسموح بها للعميل؛ أما الذي يطلب نطاقًا غير مسموح به للعميل فيُرفض كله بالرمز invalid_scope، ولا يُضيَّق بصمت أبدًا.

يكتب خادم الإرسال عبارات كل غوصة. وهو يطلب vocab:generate وحده، فلا يستطيع رمزٌ يتسرّب منه قراءة استخدام Luba.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=vocab:generate" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/vocab/stream" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"level":2,"source_lang":"en","target_lang":"zh","count":8}'

لوحة العمليات عملية ثانية على جانب الخادم بمعرّف العميل وسرّه نفسيهما. وهي تطلب usage:read وحده، وتقرأ ما تبقّى من الحصة.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=usage:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/usage" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

تعمل العمليتان كلتاهما على خوادم Luba. يطلب الجهاز اللوحي في المقصورة العبارات من خادم الإرسال، ولا يحمل السرّ ولا أي رمز أبدًا، لأن كل ما على جهاز يستطيع الراكب لمسه يمكن قراءته. ويشرح قسم «احتفظ بالأسرار والرموز على خادم» في دليل المصادقة السبب.

العميل نفسه كمشروع يمكنك استنساخه وتشغيله: integrations/luba-dive-deck

Farducks: الـ Batter Rewards

Farducks سلسلة متاجر صغيرة للسمك والبطاطا المقلية. وبينما يُقلى الطلب، يطلب تطبيق الولاء Batter Rewards من الخادم الخلفي الخاص بـ Farducks خطة درس قصيرة، ثم يقرؤها. يستدعي التطبيق وأجهزة الدفع الخادم الخلفي لـ Farducks، ولا يستدعيان Lingara أبدًا، فلا يحمل أيٌّ منهما السرّ.

تنشئ Farducks عميلًا واحدًا، Farducks Batter Rewards، مسموحًا له بـ«إنشاء خطط الدروس» (lesson_plans:write) و«قراءة خطط الدروس» (lesson_plans:read)، ويُفوتَر على «الحصة المضمّنة في خطتك» (allowance). هذه هي طريقة الفوترة الوحيدة التي يمكن إنشاء عميل بها اليوم، وتُثبَّت فوترة العميل عند إنشائه. أما الطريقة الأخرى، metered («الدفع حسب الاستخدام»)، فموصوفة في قسم «من يدفع ثمن الاستدعاء» في دليل المصادقة.

يطلب الخادم الخلفي lesson_plans:write وحده وينشئ الخطة. يُبثّ الرد، ويحمل حدث started فيه المعرّف plan_id الخاص بالخطة.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:write" | jq -r '.access_token // error(.error)')"

curl -N -X POST "https://api.getlingara.com/v1/lesson-plans" \
  -H "Authorization: Bearer $LINGARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"context":"Ordering food at a night market","source_lang":"en","target_lang":"zh","level":2}'

عيّن ID إلى قيمة plan_id تلك، ثم اطلب lesson_plans:read واقرأ الخطة. يمكن لاستبدال واحد أن يطلب عدة نطاقات من نطاقات العميل، مفصولة بمسافات في scope؛ أما كل أمر هنا فيطلب نطاقًا واحدًا، لأن كلًّا منها مؤلَّف من استدعاء واحد.

export LINGARA_TOKEN="$(curl -sS --fail-with-body -X POST "https://api.getlingara.com/oauth/token" \
  -u "$LINGARA_CLIENT_ID:$LINGARA_CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  --data-urlencode "scope=lesson_plans:read" | jq -r '.access_token // error(.error)')"

curl "https://api.getlingara.com/v1/lesson-plans/$ID" \
  -H "Authorization: Bearer $LINGARA_TOKEN"

في أحد الأيام يُلصق السرّ في تذكرة دعم. في صفحة عمليات التكامل، تضغط Farducks «سر جديد» وتنشره على الخادم الخلفي، وتنتظر حتى يتوقف تاريخ «آخر استخدام» للسرّ القديم عن التغيّر، ثم تضغط «إلغاء» على السرّ القديم. ومن تلك اللحظة يُرفض كل رمز وصول حُصل عليه باستبدال السرّ القديم. ويشرح قسم «تدوير سرّ» في دليل المصادقة حدّ السرّين، ولماذا لا يمكن إلغاء السرّ الوحيد للعميل.

العميل نفسه كمشروع يمكنك استنساخه وتشغيله: integrations/farducks-batter-rewards

إلى أين بعد ذلك

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

إذا اختلفت ترجمةٌ عن المرجع الإنجليزي، فالمرجع الإنجليزي هو الصحيح.