چگونه یک کلاینت 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

قدم بعدی

رهنمای تصدیق هویت خطاهای تبادله، کاری که هنگام منقضی شدن توکن باید کرد و قاعدهٔ چرخاندن را پوشش می‌دهد. رهنمای نسخه‌ها نسخه‌ای را که کلاینت به آن بسته شده است، و شیوهٔ انتخاب نسخهٔ دیگری برای یک فراخوانی را پوشش می‌دهد.

اگر ترجمه با مرجع انگلیسی فرق داشته باشد، مرجع انگلیسی درست است.