अपलोड

जारी रखे जा सकने वाले अपलोड: अपलोड सत्र बनाएँ, बाइट पूरे या भागों में भेजें, अपलोड पूरा करें और उसके पूर्णता कार्य पर नज़र रखें।

इस समूह के ऑपरेशन, उनके एक्सेस नियम, पुनः प्रयास नियम, पैरामीटर और जवाबों के साथ। हर अनुरोध में एक कुंजी होती है: Authorization: Bearer <कुंजी> (“प्रमाणीकरण” देखें)।

ऑपरेशन

अपलोड के प्राप्त भाग सूचीबद्ध करें

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

उदाहरण

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 · पुनः प्रयास: अपलोड फिर से पढ़ें, फिर तय करें

बॉडी को लंबित मल्टीपार्ट अपलोड के भाग 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

उदाहरण

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 · पुनः प्रयास: कार्य फिर से पढ़ें, फिर तय करें

लंबित अपलोड का पूरा होना अनुरोध के भीतर करने के बजाय वर्कर सेवा के लिए कतार में लगाता है और तुरंत 202 के साथ जॉब लौटाता है; उसे getCompletionJob से देखें। उसी अपलोड के लिए इसे दोबारा कॉल करने पर वही जॉब मिलता है, और जो जॉब किसी अस्थायी कारण से विफल हुआ था उसे फिर कतार में लगाया जाता है। कतार में लगे जॉब का अर्थ यह नहीं कि आर्टिफ़ैक्ट प्रकाशित हो गया: केवल completed का यही अर्थ है। अपलोड अब लंबित न हो तो 409 upload_state; कॉलर के 100 खुले जॉब हों या सर्वर के 10 000, तो 507 queue_full।

पैरामीटर

नाम	स्थान	प्रकार	आवश्यक	नियम
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)	नहीं	आरंभ करने वाली प्रबंधित कुंजी की वैकल्पिक ID; उसका गोपनीय मान कभी नहीं।
errorCode	string	हाँ	null हो सकता है

प्रतिक्रियाएँ: 202, 400, 401, 403, 404, 405, 409, 422, 503, 507

उदाहरण

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)	नहीं	आरंभ करने वाली प्रबंधित कुंजी की वैकल्पिक ID; उसका गोपनीय मान कभी नहीं।
errorCode	string	हाँ	null हो सकता है

प्रतिक्रियाएँ: 200, 400, 401, 403, 404, 409, 422, 503, 507

उदाहरण

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 से वर्णित एक फ़ाइल के लिए अपलोड आरक्षित करता है; सत्र (pending, 7 दिन तक वैध) और उसका Location लेकर 201 लौटाता है। 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

उदाहरण

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 का अर्थ है कि आर्टिफ़ैक्ट उसी ID के अंतर्गत प्रकाशित हो चुका है। इसे केवल अपलोड का निर्माता देख सकता है; किसी और के लिए यह 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

उदाहरण

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

उदाहरण

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

उदाहरण

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

उदाहरण

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