التوثيق/الاتصال/لوحتك الخاصة/أمثلة·7 / 9

أمثلة

مهام شائعة لنظامك وللدعم — بأمر أو أمرين لكل منها. العنوان والرمز في متغيّرات، كما في صفحة «الاستدعاءات».

  1. أنشئ عميلًا

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

    على خادمك
    curl -s "$VELI/clients" \
      -H "Authorization: Bearer $VELI_TOKEN" \
      -H "content-type: application/json" \
      -H "Idempotency-Key: order-88123:new" \
      -d '{"name": "order-88123", "days": 30, "change": {"devices": 3, "external": "88123", "tags": ["month"], "meta": {"order": "88123"}}}'
  2. تمديد شهر

    تُضاف المدة إلى النهاية، وللمنتهي — من الآن. ومع المفتاح لا يمدّد تكرار الطلب مرتين.

    على خادمك
    curl -s "$VELI/clients/order-88123" \
      -H "Authorization: Bearer $VELI_TOKEN" \
      -H "content-type: application/json" \
      -H "Idempotency-Key: order-88123:extend" \
      -d '{"change": {"days": 30}}'
  3. الرابط ورمز QR وأزرار التطبيقات

    الرابط في link، والصفحة بالأزرار في page، وروابط «إضافة إلى …» الجاهزة في apps، والمتبقي في left. ورمز QR للمحادثة أو الرسالة — PNG.

    على خادمك
    curl -s "$VELI/clients/order-88123" \
      -H "Authorization: Bearer $VELI_TOKEN" | jq -r .link
    curl -s "$VELI/clients/order-88123/qr?format=png&size=512" \
      -H "Authorization: Bearer $VELI_TOKEN" -o qr.png
    curl -s "$VELI/clients/order-88123" \
      -H "Authorization: Bearer $VELI_TOKEN" | jq '{page, apps, left}'
  4. البحث عن العملاء بالمعرّف الخارجي

    قد يكون للشخص عدة اشتراكات — الرد قائمة دائمًا.

    على خادمك
    curl -s "$VELI/clients?external=88123" \
      -H "Authorization: Bearer $VELI_TOKEN" | jq -r '.clients[] | "\(.name) \(.status) \(.left.days)"'

تكرار بلا عواقب

تُرسل الأنظمة الإشعار مرة أخرى، ويضغط الناس مرتين، ويسقط الخادم بين الطلب والرد. الترويسة Idempotency-Key في POST تجعل التكرار آمنًا.

  • المفتاح نفسه والطلب نفسه — الرد نفسه، دون إجراء ثانٍ، مع الترويسة Idempotent-Replayed: true.
  • المفتاح نفسه مع طلب آخر — 409 idempotency: المفتاح استُخدم لشيء آخر.
  • تتذكر اللوحة المفتاح يومًا واحدًا، ولكل رمز مفاتيحه. المفتاح حتى 128 حرفًا مرئيًا؛ والأنسب رقم الطلب والإجراء: order-88123:extend.
  • المفتاح لإجراء واحد: للتمديد وللإنشاء مفتاحان مختلفان، وإلا حصل الطلب الثاني على رد الأول.
تكرار بالمفتاح نفسه
HTTP/1.1 200 OK
idempotent-replayed: true

{"done": 1}