التوثيق/الاتصال/لوحتك الخاصة/أمثلة·7 / 9
أمثلة
مهام شائعة لنظامك وللدعم — بأمر أو أمرين لكل منها. العنوان والرمز في متغيّرات، كما في صفحة «الاستدعاءات».
أنشئ عميلًا
لمدة شهر وثلاثة أجهزة، ورقم الطلب معرّفًا خارجيًا. مفتاح التكرار هو رقم الطلب: الطلب المكرر يحصل على الرد نفسه، لا على عميل ثانٍ.
على خادمك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"}}}'تمديد شهر
تُضاف المدة إلى النهاية، وللمنتهي — من الآن. ومع المفتاح لا يمدّد تكرار الطلب مرتين.
على خادمك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}}'الرابط ورمز 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}'البحث عن العملاء بالمعرّف الخارجي
قد يكون للشخص عدة اشتراكات — الرد قائمة دائمًا.
على خادمك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}