API رونویسی طولانی بعد از پذیرش درخواست چه چیزی برگرداند؟

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

برای سارا، توسعه‌دهندهٔ بک‌اند یک سرویس رونویسی فایل صوتی، پاسخ مفید این است: پس از پذیرش کار، HTTP 202 همراه با job_id، status و status_url برگردانید؛ آدرس پیگیری را در هدر Location نیز بگذارید. کلاینت باید بتواند تنها با همین رسید، وضعیت را بررسی کند و در پایان یا result_url بگیرد یا خطایی قابل‌فهم ببیند. اتصال اولیه را تا پایان رونویسی باز نگه ندارید.

۱. رسید پذیرش، نتیجهٔ رونویسی نیست

طبق RFC 9110، وضعیت 202 یعنی درخواست برای پردازش پذیرفته شده، نه اینکه پردازش با موفقیت تمام شده است. خود این پاسخ تضمین نمی‌کند کار در آینده موفق شود. RFC پیشنهاد می‌کند نمایش پاسخ، وضعیت فعلی و راهی برای پایش آن را معرفی کند. بنابراین پاسخ «درخواست ثبت شد» بدون شناسه و آدرس پیگیری، برای ساخت کلاینت قابل‌اتکا کافی نیست.

قرارداد پیشنهادی این مقاله چنین است: POST /transcriptions کار را ایجاد می‌کند؛ GET /transcriptions/{job_id} وضعیت را می‌دهد؛ و پس از موفقیت، result_url محل دریافت متن است. پاسخ اولیه شامل job_id، status با مقدار queued و status_url است. هدر Location همان آدرس وضعیت را تکرار می‌کند و Retry-After فاصلهٔ پیشنهادی تا پیگیری بعدی را می‌دهد. استفاده از این هدرها در این قرارداد یک انتخاب طراحی مطابق الگوی درخواست‌ـ‌پاسخ ناهمگام Azure است، نه ادعای الزامی‌بودن آن‌ها برای همهٔ پاسخ‌های 202.

۲. وضعیت باید به تصمیم کلاینت تبدیل شود

چهار وضعیت برای این مسئله کافی است: queued یعنی هنوز نوبت پردازش نرسیده، running یعنی پردازش آغاز شده، succeeded یعنی نتیجه آماده است و failed یعنی این تلاش پایان ناموفق داشته است. دو وضعیت آخر نهایی‌اند و کلاینت باید polling را متوقف کند. اگر لغو کار واقعاً پشتیبانی می‌شود، می‌توانید canceled را اضافه کنید؛ صرفاً برای کامل به‌نظررسیدن قرارداد آن را وعده ندهید. در این طراحی، GET وضعیت برای یک کار موجود، حتی اگر خود کار failed باشد، پاسخ HTTP 200 می‌دهد: واکشی وضعیت موفق بوده، اما رونویسی شکست خورده است.

در succeeded، فیلد result_url باید حاضر باشد؛ در failed، شیء error با code پایدار، message قابل‌نمایش و retryable برگردانید. مثلاً کد UNSUPPORTED_AUDIO با retryable=false می‌گوید ارسال مجدد همان فایل راه‌حل نیست. در وضعیت‌های غیرنهایی، نتیجه را آماده نشان ندهید. اگر درصد واقعی ندارید، progress را null بگذارید: تعداد ثانیه‌های صوت پردازش‌شده همیشه برابر با درصد کل زمان محاسبات، جداسازی گویندگان و آماده‌سازی خروجی نیست.

برای رابط کاربری و عملیات، created_at و updated_at را با زمان UTC ثبت کنید؛ updated_at باید زمان تغییر واقعی وضعیت یا پیشرفت باشد، نه زمان آخرین GET. اگر سابقه یا نتیجه حذف می‌شود، expires_at و سیاست انقضا را هم اعلام کنید. این فیلدها بخشی از قرارداد پیشنهادی‌اند، نه فیلدهای استاندارد HTTP. برای شروع، شناسه و مسیر پیگیری ضروری‌تر از تخمین زمان پایان‌اند؛ تخمین بی‌پشتوانه فقط یک وعدهٔ نادقیق به کاربر اضافه می‌کند.

۳. نمونهٔ اجرایی: از رسید تا دریافت متن

کد زیر با کتابخانهٔ استاندارد Python یک سرور محلی و یک کلاینت می‌سازد. ورودی، نشانی فرضی فایل صوتی است؛ هیچ فایلی دانلود نمی‌شود و متن خروجی ثابت است. برای قطعی‌بودن آزمایش، اولین GET وضعیت running و دومین GET وضعیت succeeded می‌دهد؛ این تغییر وضعیت بر اساس تعداد درخواست فقط ابزار نمایش قرارداد است و نباید در سرویس واقعی استفاده شود.

```python
import json
import sys
import threading
import time
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from urllib.request import Request, urlopen

job = None
polls = 0

class Handler(BaseHTTPRequestHandler):
def log_message(self, *args):
pass

def send_json(self, status, body, headers=None):
data = json.dumps(body, ensure_ascii=False).encode('utf-8')
self.send_response(status)
self.send_header('Content-Type', 'application/json; charset=utf-8')
self.send_header('Content-Length', str(len(data)))
self.send_header('Cache-Control', 'no-store')
for key, value in (headers or {}).items():
self.send_header(key, value)
self.end_headers()
self.wfile.write(data)

def do_POST(self):
global job, polls
if self.path != '/transcriptions':
return self.send_json(404, {'error': 'not_found'})
try:
size = int(self.headers.get('Content-Length', '0'))
body = json.loads(self.rfile.read(size))
if not isinstance(body.get('audio_url'), str) or not body['audio_url']:
raise ValueError('audio_url required')
except (ValueError, AttributeError):
return self.send_json(400, {'error': 'invalid_input'})
polls = 0
job = {
'job_id': 'tr_demo',
'status': 'queued',
'status_url': self.server.base + '/transcriptions/tr_demo',
'progress': None
}
self.send_json(202, job, {
'Location': job['status_url'],
'Retry-After': '1'
})

def do_GET(self):
global polls
if job is None:
return self.send_json(404, {'error': 'not_found'})
if self.path == '/transcriptions/tr_demo':
polls += 1
body = dict(job)
body['status'] = 'running' if polls == 1 else 'succeeded'
if body['status'] == 'succeeded':
body['result_url'] = self.server.base + '/results/tr_demo'
headers = {'Retry-After': '1'} if polls == 1 else {}
return self.send_json(200, body, headers)
if self.path == '/results/tr_demo' and polls >= 2:
return self.send_json(200, {'text': 'سلام دنیا'})
self.send_json(404, {'error': 'not_found'})

def fetch(url, body=None):
data = None if body is None else json.dumps(body).encode('utf-8')
request = Request(url, data=data, headers={'Content-Type': 'application/json'})
with urlopen(request, timeout=5) as response:
return response.status, response.headers, json.load(response)

def main():
if len(sys.argv) != 2:
raise SystemExit('Usage: python demo.py AUDIO_URL')
server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
server.base = 'http://127.0.0.1:' + str(server.server_port)
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
try:
code, headers, receipt = fetch(
server.base + '/transcriptions', {'audio_url': sys.argv[1]}
)
print(code, receipt['job_id'], receipt['status'])
status_url = headers['Location']
delay = int(headers['Retry-After'])
for _ in range(10):
time.sleep(delay)
code, headers, status = fetch(status_url)
print(code, status['status'])
if status['status'] == 'succeeded':
_, _, result = fetch(status['result_url'])
print(result['text'])
break
if status['status'] == 'failed':
raise RuntimeError(status['error'])
delay = int(headers.get('Retry-After', '1'))
else:
raise TimeoutError('Polling budget exhausted; keep status_url')
finally:
server.shutdown()
server.server_close()
thread.join()

if __name__ == '__main__':
main()
```

کد را در demo.py ذخیره کنید و دستور زیر را اجرا کنید. ورودی نمونه صرفاً یک نشانی است و نیاز به دسترسی اینترنت ندارد. سرور یک پورت آزاد محلی انتخاب می‌کند و پس از اجرای آزمایش بسته می‌شود.

```bash
python demo.py https://example.com/audio.wav
```

خروجی مورد انتظار زیر است. نکتهٔ اصلی تفاوت 202 پذیرش با 200 واکشی وضعیت است؛ هیچ‌کدام به‌تنهایی موفقیت رونویسی را اثبات نمی‌کنند. کلاینت موفقیت را از status=succeeded می‌فهمد و سپس نتیجه را دریافت می‌کند.

```other
202 tr_demo queued
200 running
200 succeeded
سلام دنیا
```

۴. کجا این قرارداد می‌شکند و چه چیزی باید اضافه شود؟

خطر مهم، اعلام پذیرش پیش از ثبت پایدار کار است: اگر سرور 202 بدهد و سپس پیش از ذخیره‌سازی از کار بیفتد، رسید به کاری اشاره می‌کند که وجود ندارد. پیش از پاسخ، کار را پایدار ثبت کنید و تحویل آن به صف را با سازوکاری قابل‌بازیابی، مثلاً outbox، هماهنگ کنید. همچنین قطع اتصال POST می‌تواند کلاینت را به ارسال دوباره وادار کند؛ یک قرارداد مشخص برای کلید idempotency لازم است تا تکرار همان درخواست ناخواسته دو رونویسی و دو هزینه ایجاد نکند. نمونهٔ آموزشی هیچ‌یک از این تضمین‌ها را ندارد.

Timeout در polling به معنی failed شدن کار نیست؛ فقط یعنی کلاینت فعلاً پیگیری را متوقف کرده است. status_url را نگه دارید تا پیگیری از سر گرفته شود. در تولید، برای خطاهای موقت شبکه عقب‌نشینی افزایشی با سقف و کمی تصادفی‌سازی اضافه کنید. Retry-After می‌تواند تعداد ثانیه یا تاریخ HTTP باشد؛ کلاینت نمونه فقط شکل عددی قراردادی این سرور را می‌خواند. تعداد درخواست‌های زیاد هزینهٔ polling است و فاصلهٔ زیاد هم کشف پایان کار را عقب می‌اندازد.

مسیر وضعیت و نتیجه باید مانند فایل صوتی مجوز دسترسی داشته باشند؛ دانستن job_id نباید مجوز خواندن متن باشد. اگر result_url امضاشده و کوتاه‌عمر است، زمان انقضای آن را جدا از عمر سابقهٔ کار مشخص کنید. لینک منقضی‌شده لزوماً به معنی شکست رونویسی نیست. سیاست پاسخ به کار ناشناخته یا منقضی‌شده، از جمله انتخاب 404 یا 410، نیز باید مستند باشد تا کلاینت آن را با «هنوز در صف است» اشتباه نگیرد.

برای صفحه‌ای که کاربر هر چند ثانیه آن را بررسی می‌کند، polling ساده و قابل‌ازسرگیری است. اگر مصرف‌کننده یک بک‌اند با تعداد زیادی کار است، webhook می‌تواند درخواست‌های بی‌حاصل را کم کند، اما احراز اصالت پیام، تلاش مجدد تحویل و حذف اثر پیام تکراری را هم لازم دارد؛ مسیر GET وضعیت همچنان مرجع بازیابی مفیدی است. اگر هدف نمایش کلمه‌ها هم‌زمان با صحبت کاربر است، این رویکرد انتخاب اشتباهی است: آن مسئله به خروجی جریانی نیاز دارد، نه صرفاً رسید یک کار طولانی.

منابع

RFC 9110 — 202 Accepted
https://www.rfc-editor.org/rfc/rfc9110.html#section-15.3.3

Microsoft Azure Architecture Center — Asynchronous Request-Reply pattern
https://learn.microsoft.com/en-us/azure/architecture/patterns/async-request-reply

MDN — Retry-After header
https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Retry-After

Python documentation — http.server
https://docs.python.org/3/library/http.server.html

No comments yet