عمليات الرفع

عمليات رفع قابلة للاستئناف: أنشئ جلسة رفع، وأرسل البايتات كاملة أو على أجزاء، وأكملها، وتابع مهمة الإكمال.

عمليات هذه المجموعة مع قاعدة الوصول وقاعدة إعادة المحاولة والمعلمات والاستجابات. يحمل كل طلب مفتاحًا: Authorization: Bearer <key> (راجع «المصادقة»).

العمليات

عرض قائمة الأجزاء المستلمة من عملية رفع

GET HEAD /api/v1/repositories/{repository}/uploads/{id}/parts

الوصول: إذن المستودع: upload.read; مفاتيح الملفات: write · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد partBytes، وهو حجم الجزء الذي تحدد لعملية الرفع هذه عند إنشائها (8 MiB، ويُضاعَف الحجم للملفات التي تتطلب أكثر من 10 000 جزء؛ ولا يكون أقصر إلا الجزء الأخير)، والأجزاء المخزَّنة بالفعل مع رقمها التسلسلي وحجمها وSHA-256. اقرأه قبل استئناف رفع متعدد الأجزاء انقطع، وأرسل الأجزاء الناقصة فقط عبر putUploadPart. لا يراه إلا منشئ عملية الرفع؛ وبالنسبة لغيره تكون النتيجة 404.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`partBytes`	integer	لا	8388608–1073741824; لكل جزء هذا الحجم عدا الجزء الأخير.
`items`	مصفوفة من object	لا	—
`items[].index`	integer	نعم	0–9999
`items[].size`	integer	نعم	1–1073741824
`items[].sha256`	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

رفع جزء واحد

PUT /api/v1/repositories/{repository}/uploads/{id}/parts/{index}

الوصول: إذن المستودع: upload.write; مفاتيح الملفات: write · إعادة المحاولة: أعد قراءة عملية الرفع، ثم قرّر

يخزّن المتن (body) جزءًا برقم index (يبدأ من 0) في عملية رفع متعدد الأجزاء معلّقة؛ ويجب أن يساوي طوله partBytes تمامًا (من listUploadParts)، أو المتبقي للجزء الأخير، وأن يكون X-Content-SHA256 هو SHA-256 بالنظام السداسي عشري وبأحرف صغيرة لهذه البايتات، وإلا كانت النتيجة 422. يجوز أن تصل الأجزاء بأي ترتيب، لكن عملية الرفع تقبل طلبًا واحدًا في كل مرة (والطلب المتزامن الآخر يحصل على 503 busy)؛ وإعادة إرسال جزء بقيمة التجزئة نفسها آمنة، أما قيمة تجزئة مختلفة لرقم مخزَّن بالفعل فهي 409 part_mismatch. وعند تخزين كل الأجزاء استدعِ completeUpload أو enqueueCompletion.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`id`	المسار	string (uuid)	نعم	—
`index`	المسار	integer	نعم	0–9999
`X-Content-SHA256`	الترويسة	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة

نص الطلب (application/octet-stream)

الاستجابات: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/parts/$INDEX" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "X-Content-SHA256: $X_CONTENT_SHA256" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file

إكمال عملية رفع في الخلفية

POST /api/v1/repositories/{repository}/uploads/{id}/complete-async

الوصول: إذن المستودع: upload.complete; مفاتيح الملفات: write · إعادة المحاولة: أعد قراءة المهمة، ثم قرّر

يضع إكمال عملية رفع معلّقة في طابور خدمة العامل (worker) بدلًا من تنفيذه داخل الطلب، ويعيد المهمة فورًا مع 202؛ تابعها عبر getCompletionJob. وإعادة استدعائه لعملية الرفع نفسها تعيد المهمة نفسها، أما المهمة التي فشلت لسبب عابر فتُوضع في الطابور من جديد. وجود مهمة في الطابور لا يعني أن المُخرَج نُشر: النشر يعني الحالة completed فقط. والنتيجة 409 upload_state إذا لم تعد عملية الرفع معلّقة؛ و507 queue_full عندما يكون لدى المستدعي 100 مهمة مفتوحة أو لدى الخادم 10 000.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`id`	المسار	string (uuid)	نعم	—

الاستجابة 202

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`uploadId`	string (uuid)	نعم	—
`repository`	string	نعم	—
`owner`	string	نعم	—
`status`	string	نعم	إحدى القيم: `queued`, `running`, `completed`, `failed`
`generation`	integer	نعم	0–2147483647
`attempts`	integer	نعم	0 على الأقل
`credentialId`	string (uuid)	لا	معرّف اختياري للمفتاح المُدار الذي بدأ العملية؛ وليس سرّه أبدًا.
`errorCode`	string	نعم	يمكن أن يكون null

الاستجابات: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete-async" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

الحصول على مهمة إكمال

GET HEAD /api/v1/jobs/{id}

الوصول: إذن المستودع: job.read; مفاتيح الملفات: write · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد حالة مهمة إكمال وُضعت في الطابور عبر enqueueCompletion: queued أو running أو completed (تم نشر عملية الرفع) أو failed مع errorCode، إضافةً إلى عدد المحاولات. يحاول العامل حتى خمس مرات بفواصل زمنية متزايدة؛ أما أخطاء مثل integrity_mismatch فتُفشِل المهمة فورًا. لا يراها إلا منشئ المهمة؛ وبالنسبة لغيره تكون النتيجة 404.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`uploadId`	string (uuid)	نعم	—
`repository`	string	نعم	—
`owner`	string	نعم	—
`status`	string	نعم	إحدى القيم: `queued`, `running`, `completed`, `failed`
`generation`	integer	نعم	0–2147483647
`attempts`	integer	نعم	0 على الأقل
`credentialId`	string (uuid)	لا	معرّف اختياري للمفتاح المُدار الذي بدأ العملية؛ وليس سرّه أبدًا.
`errorCode`	string	نعم	يمكن أن يكون null

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

curl -X GET "$ARKVORY_URL/api/v1/jobs/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

إنشاء جلسة رفع

POST /api/v1/repositories/{repository}/uploads

الوصول: إذن المستودع: upload.create; مفاتيح الملفات: write · إعادة المحاولة: آمن للتكرار مع Idempotency-Key نفسه

يحجز عملية رفع لملف واحد يصفه name وsize (سلسلة نصية عشرية) وsha256 وlabels وmetadata الاختياريان؛ ويعيد 201 مع الجلسة (pending، صالحة لمدة 7 أيام) وLocation الخاص بها. المفتاح Idempotency-Key (من 1 إلى 128 حرفًا من الأحرف والأرقام و_.:-) مطلوب: المفتاح نفسه مع الوصف نفسه يعيد الجلسة نفسها، ومع وصف مختلف يكون الناتج 409 idempotency_mismatch. ويُحجز الحجم فورًا من حصة تخزين المستودع ومن سعة الخادم (507). بعد ذلك أرسل البايتات كاملة عبر putUploadContent، أو على أجزاء عبر putUploadPart ثم أنهِ بـ completeUpload.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`Idempotency-Key`	الترويسة	string	نعم	عدد الأحرف: 128 كحد أقصى

نص الطلب (application/json)

الحقل	النوع	مطلوب	القواعد
`name`	string	نعم	عدد الأحرف: 1–240
`size`	string	نعم	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
`sha256`	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة
`labels`	مصفوفة من string	لا	عدد العناصر: 32 كحد أقصى; كل عنصر: عدد الأحرف: 64 كحد أقصى
`metadata`	قاموس من string	لا	عدد الإدخالات: 32 كحد أقصى

الاستجابة 201

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`repository`	string	نعم	—
`status`	string	نعم	إحدى القيم: `pending`, `available`, `cancelled`
`createdAt`	string (date-time)	نعم	—
`expiresAt`	string (date-time)	نعم	—
`descriptor`	object	نعم	—
`descriptor.name`	string	نعم	عدد الأحرف: 1–240
`descriptor.size`	string	نعم	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
`descriptor.sha256`	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة
`descriptor.labels`	مصفوفة من string	لا	عدد العناصر: 32 كحد أقصى; كل عنصر: عدد الأحرف: 64 كحد أقصى
`descriptor.metadata`	قاموس من string	لا	عدد الإدخالات: 32 كحد أقصى

الاستجابات: 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507

مثال

bash

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name":"<name>","size":"1024","sha256":"<sha256: SHA-256>"}'

الحصول على عملية رفع

GET HEAD /api/v1/repositories/{repository}/uploads/{id}

الوصول: إذن المستودع: upload.read; مفاتيح الملفات: write · إعادة المحاولة: آمن للتكرار (قراءة)

يعيد الجلسة مع status (pending، أو available بعد النشر، أو cancelled) وتاريخ انتهائها والواصف المُعلَن. بعد ضياع الردّ على putUploadContent أو completeUpload اقرأ هذا أولًا: القيمة available تعني أن المُخرَج نُشر بالمعرّف نفسه. لا يراها إلا منشئ عملية الرفع؛ وبالنسبة لغيره تكون النتيجة 404.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`repository`	string	نعم	—
`status`	string	نعم	إحدى القيم: `pending`, `available`, `cancelled`
`createdAt`	string (date-time)	نعم	—
`expiresAt`	string (date-time)	نعم	—
`descriptor`	object	نعم	—
`descriptor.name`	string	نعم	عدد الأحرف: 1–240
`descriptor.size`	string	نعم	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
`descriptor.sha256`	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة
`descriptor.labels`	مصفوفة من string	لا	عدد العناصر: 32 كحد أقصى; كل عنصر: عدد الأحرف: 64 كحد أقصى
`descriptor.metadata`	قاموس من string	لا	عدد الإدخالات: 32 كحد أقصى

الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507

مثال

bash

curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

إلغاء عملية رفع

DELETE /api/v1/repositories/{repository}/uploads/{id}

الوصول: إذن المستودع: upload.cancel; مفاتيح الملفات: write · إعادة المحاولة: أعد قراءة عملية الرفع، ثم قرّر

يلغي عملية رفع معلّقة ويعيدها بالحالة cancelled؛ أما عملية الرفع المنشورة فلا يمكن إلغاؤها (409 upload_state). تُخفى البايتات المستلمة فورًا لكنها تبقى محجوزة من حصة التخزين إلى أن يزيلها التنظيف الفعلي أثناء التشغيل في المستودع (setCleanup، وهو معطّل افتراضيًا) بعد انقضاء فترة السماح.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`repository`	string	نعم	—
`status`	string	نعم	إحدى القيم: `pending`, `available`, `cancelled`
`createdAt`	string (date-time)	نعم	—
`expiresAt`	string (date-time)	نعم	—
`descriptor`	object	نعم	—
`descriptor.name`	string	نعم	عدد الأحرف: 1–240
`descriptor.size`	string	نعم	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
`descriptor.sha256`	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة
`descriptor.labels`	مصفوفة من string	لا	عدد العناصر: 32 كحد أقصى; كل عنصر: عدد الأحرف: 64 كحد أقصى
`descriptor.metadata`	قاموس من string	لا	عدد الإدخالات: 32 كحد أقصى

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash

curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

رفع الملف كاملًا في طلب واحد

PUT /api/v1/repositories/{repository}/uploads/{id}/content

الوصول: إذن المستودع: upload.write, upload.complete; مفاتيح الملفات: write · إعادة المحاولة: أعد قراءة عملية الرفع، ثم قرّر

يبثّ متن الطلب بوصفه المحتوى الكامل لعملية رفع معلّقة، ويقارنه بالحجم المُعلَن وSHA-256 (422 عند عدم التطابق)، وينشر المُخرَج؛ والردّ هو عملية الرفع بالحالة available. الطلب الذي انقطع لا يترك شيئًا يمكن استئنافه: اقرأ عملية الرفع عبر getUpload، ثم أرسل الملف من جديد من البايت صفر. لا يصلح لعملية رفع لها أجزاء بالفعل (409 upload_state)؛ كما يجب أن ينتهي الطلب الواحد خلال مهلة الرفع في الخادم (30 دقيقة افتراضيًا)، فأرسل الملفات الكبيرة على أجزاء.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`id`	المسار	string (uuid)	نعم	—

نص الطلب (application/octet-stream)

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`repository`	string	نعم	—
`status`	string	نعم	إحدى القيم: `pending`, `available`, `cancelled`
`createdAt`	string (date-time)	نعم	—
`expiresAt`	string (date-time)	نعم	—
`descriptor`	object	نعم	—
`descriptor.name`	string	نعم	عدد الأحرف: 1–240
`descriptor.size`	string	نعم	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
`descriptor.sha256`	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة
`descriptor.labels`	مصفوفة من string	لا	عدد العناصر: 32 كحد أقصى; كل عنصر: عدد الأحرف: 64 كحد أقصى
`descriptor.metadata`	قاموس من string	لا	عدد الإدخالات: 32 كحد أقصى

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash

curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/content" \
  -H "Authorization: Bearer $ARKVORY_TOKEN" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @file

إكمال عملية رفع

POST /api/v1/repositories/{repository}/uploads/{id}/complete

الوصول: إذن المستودع: upload.complete; مفاتيح الملفات: write · إعادة المحاولة: أعد قراءة عملية الرفع، ثم قرّر

يجمّع الأجزاء المخزَّنة بالترتيب، ويتحقق من الملف كاملًا مقابل الحجم المُعلَن وSHA-256، وينشر المُخرَج؛ ويعيد عملية الرفع بالحالة available. وإعادة استدعائه لعملية رفع منشورة تعيد النتيجة نفسها، فيصلح بذلك أيضًا لاستعادة إكمال ضاع ردّه. الجزء الناقص هو 409 parts_incomplete، وعدم تطابق المحتوى هو 422؛ وللملفات الكبيرة جدًا التي قد ينتهي فيها زمن الطلب استخدم enqueueCompletion بدلًا منه.

المعلمات

الاسم	الموضع	النوع	مطلوب	القواعد
`repository`	المسار	string	نعم	يطابق النمط `^[a-z0-9][a-z0-9_-]{0,63}$`
`id`	المسار	string (uuid)	نعم	—

الاستجابة 200

الحقل	النوع	مطلوب	القواعد
`id`	string (uuid)	نعم	—
`repository`	string	نعم	—
`status`	string	نعم	إحدى القيم: `pending`, `available`, `cancelled`
`createdAt`	string (date-time)	نعم	—
`expiresAt`	string (date-time)	نعم	—
`descriptor`	object	نعم	—
`descriptor.name`	string	نعم	عدد الأحرف: 1–240
`descriptor.size`	string	نعم	عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية
`descriptor.sha256`	string	نعم	SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة
`descriptor.labels`	مصفوفة من string	لا	عدد العناصر: 32 كحد أقصى; كل عنصر: عدد الأحرف: 64 كحد أقصى
`descriptor.metadata`	قاموس من string	لا	عدد الإدخالات: 32 كحد أقصى

الاستجابات: 200, 400, 401, 403, 404, 405, 409, 422, 503, 507

مثال

bash

curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/uploads/$ID/complete" \
  -H "Authorization: Bearer $ARKVORY_TOKEN"

عمليات الرفع ​

العمليات ​

عرض قائمة الأجزاء المستلمة من عملية رفع ​

رفع جزء واحد ​

إكمال عملية رفع في الخلفية ​

الحصول على مهمة إكمال ​

إنشاء جلسة رفع ​

الحصول على عملية رفع ​

إلغاء عملية رفع ​

رفع الملف كاملًا في طلب واحد ​

إكمال عملية رفع ​

عمليات الرفع

العمليات

عرض قائمة الأجزاء المستلمة من عملية رفع

رفع جزء واحد

إكمال عملية رفع في الخلفية

الحصول على مهمة إكمال

إنشاء جلسة رفع

الحصول على عملية رفع

إلغاء عملية رفع

رفع الملف كاملًا في طلب واحد

إكمال عملية رفع