المراحل والترقية
مراحل المُخرَج (مثل release)، والترقية بين المستودعات، وتحديد الإصدار حسب المرحلة.
عمليات هذه المجموعة مع قاعدة الوصول وقاعدة إعادة المحاولة والمعلمات والاستجابات. يحمل كل طلب مفتاحًا: Authorization: Bearer <key> (راجع «المصادقة»).
العمليات
عرض قائمة مراحل مُخرَج
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/stages
الوصول: إذن المستودع: artifact.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد مراحل الترقية الحالية لمُخرَج منشور (16 كحد أقصى)، لكل منها وقت إضافتها والفاعل والتعليق.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | المسار | string (uuid) | نعم | — |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
items | مصفوفة من object | نعم | عدد العناصر: 16 كحد أقصى |
items[].artifactId | string (uuid) | نعم | — |
items[].stage | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | نعم | — |
items[].actor | string | نعم | — |
items[].comment | string | نعم | عدد الأحرف: 1024 كحد أقصى; يمكن أن يكون null |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"إضافة مرحلة إلى مُخرَج
PUT /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
الوصول: إذن المستودع: artifact.promote, artifact.read; مفاتيح الملفات: read, write · إعادة المحاولة: آمن للتكرار: الطلب نفسه يُحدث الأثر نفسه
يعلّم مُخرَجًا منشورًا بالمرحلة stage (من 1 إلى 32 حرفًا لاتينيًا صغيرًا أو رقمًا أو _.-، على أن تبدأ بحرف أو رقم)، مع comment اختياري حتى 1024 حرفًا، ويسجّل الحدث في سجل الترقيات. إضافة مرحلة موجودة بالفعل للمُخرَج لا تغيّر شيئًا وتُبقي الوقت الأصلي، لذا فلترقية الإصدار نفسه مرة أخرى (للتراجع بـ order=promoted) أزل المرحلة أولًا. للمُخرَج 16 مرحلة كحد أقصى (409 stage_limit).
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | المسار | string (uuid) | نعم | — |
stage | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
نص الطلب (application/json)
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
comment | string | لا | عدد الأحرف: 1024 كحد أقصى; يمكن أن يكون null |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
artifactId | string (uuid) | نعم | — |
stage | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
promotedAt | string (date-time) | نعم | — |
actor | string | نعم | — |
comment | string | نعم | عدد الأحرف: 1024 كحد أقصى; يمكن أن يكون null |
الاستجابات: 200, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
مثال
curl -X PUT "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'إزالة مرحلة من مُخرَج
DELETE /api/v1/repositories/{repository}/artifacts/{id}/stages/{stage}
الوصول: إذن المستودع: artifact.promote, artifact.read; مفاتيح الملفات: read, write · إعادة المحاولة: آمن للتكرار: الطلب نفسه يُحدث الأثر نفسه
يزيل stage من مُخرَج منشور ويسجّل الحدث في سجل الترقيات؛ وإزالة مرحلة ليست لدى المُخرَج تنجح هي الأخرى. ويتوقف تحديد الحزمة حسب هذه المرحلة عن اختيار المُخرَج فورًا.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | المسار | string (uuid) | نعم | — |
stage | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
الاستجابات: 204, 400, 401, 403, 404, 405, 409, 422, 503, 507
مثال
curl -X DELETE "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/stages/$STAGE" \
-H "Authorization: Bearer $ARKVORY_TOKEN"عرض سجل ترقيات مُخرَج
GET HEAD /api/v1/repositories/{repository}/artifacts/{id}/promotions
الوصول: إذن المستودع: artifact.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد سجل مُخرَج واحد بدءًا من الأقدم: المراحل المضافة والمزالة، والترقيات إلى مستودعات أخرى ومنها مع المُخرَج المقابل والفاعل والتعليق والوقت. تحتوي الصفحة على limit حدثًا (من 1 إلى 100، والافتراضي 50)؛ وللمتابعة اضبط after على قيمة next.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | المسار | string (uuid) | نعم | — |
after | الاستعلام | string | لا | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية |
limit | الاستعلام | string | لا | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; At most 100. |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
items | مصفوفة من object | نعم | عدد العناصر: 100 كحد أقصى |
items[].sequence | string | نعم | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية |
items[].repository | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | نعم | — |
items[].action | string | نعم | إحدى القيم: stage.added, stage.removed, promoted, received |
items[].stage | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$; يمكن أن يكون null |
items[].mode | string | نعم | إحدى القيم: copy, move, null; يمكن أن يكون null |
items[].peerRepository | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$; يمكن أن يكون null |
items[].peerArtifactId | string (uuid) | نعم | يمكن أن يكون null |
items[].actor | string | نعم | — |
items[].comment | string | نعم | عدد الأحرف: 1024 كحد أقصى; يمكن أن يكون null |
items[].occurredAt | string (date-time) | نعم | — |
next | string | نعم | يمكن أن يكون null |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"ترقية مُخرَج إلى مستودع آخر
POST /api/v1/repositories/{repository}/artifacts/{id}/promote
الوصول: إذن المستودع: artifact.read, content.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار: الطلب نفسه يُحدث الأثر نفسه
ينشر المُخرَج في target دون إرسال البايتات مرة أخرى، مع stages وcomment اختياريين؛ ويحتاج المستدعي أيضًا إلى artifact.promote في الهدف. يحدد mode السلوك: copy (الافتراضي) يُبقي المصدر؛ أما move، الذي يحتاج إلى artifact.promote هنا أيضًا، فيسحب المصدر في المعاملة نفسها وينقل مراحله، ويُرفض بالخطأ 409 إذا تعذّر حذف المصدر. الردّ 201 مع النسخة؛ وتكراره يعيد النسخة نفسها مع 200؛ وإذا كان الهدف يحوي إصدار الحزمة نفسه أعاد ذلك المُخرَج عند تطابق SHA-256، وأعاد 409 version_exists عند عدم تطابقه. ولا تُنقل مرفقات نسخة البناء ولا مسارات الملفات.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
id | المسار | string (uuid) | نعم | — |
نص الطلب (application/json)
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
target | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
mode | string | لا | إحدى القيم: copy, move |
stages | مصفوفة من string | لا | عدد العناصر: 16 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
comment | string | لا | عدد الأحرف: 1024 كحد أقصى; يمكن أن يكون null |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
repository | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
artifactId | string (uuid) | نعم | — |
sourceRepository | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
sourceArtifactId | string (uuid) | نعم | — |
mode | string | نعم | إحدى القيم: copy, move |
created | boolean | نعم | — |
stages | مصفوفة من string | نعم | عدد العناصر: 16 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
الاستجابات: 200, 201, 400, 401, 403, 404, 405, 409, 413, 415, 422, 503, 507
مثال
curl -X POST "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/artifacts/$ID/promote" \
-H "Authorization: Bearer $ARKVORY_TOKEN" \
-H "Content-Type: application/json" \
-d '{"target":"<target>"}'عرض قائمة المُخرَجات ذات المراحل
GET HEAD /api/v1/repositories/{repository}/stages
الوصول: إذن المستودع: artifact.list; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يسرد مدخلات المراحل في المستودع (المُخرَج والمرحلة والوقت والفاعل والتعليق) مرتبةً حسب المُخرَج والمرحلة، ويمكن حصرها في stage معيّنة، أو في المُخرَجات المذكورة في ids فقط (من 1 إلى 100 معرّف مفصولة بفواصل، مثلًا لعرض مراحل صفحة من الحزم دفعة واحدة). تحتوي الصفحة على limit مدخلًا (من 1 إلى 100، والافتراضي 100)؛ وللمتابعة اضبط after على قيمة next (<artifactId>/<stage>).
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
stage | الاستعلام | string | لا | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
after | الاستعلام | string | لا | — |
limit | الاستعلام | string | لا | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; At most 100. |
ids | الاستعلام | string | لا | عدد الأحرف: 3699 كحد أقصى; Up to 100 comma-separated artifact ids. |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
items | مصفوفة من object | نعم | عدد العناصر: 100 كحد أقصى |
items[].artifactId | string (uuid) | نعم | — |
items[].stage | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
items[].promotedAt | string (date-time) | نعم | — |
items[].actor | string | نعم | — |
items[].comment | string | نعم | عدد الأحرف: 1024 كحد أقصى; يمكن أن يكون null |
next | string | نعم | يمكن أن يكون null |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/stages" \
-H "Authorization: Bearer $ARKVORY_TOKEN"متابعة سجل ترقيات مستودع
GET HEAD /api/v1/repositories/{repository}/promotions
الوصول: إذن المستودع: artifact.list; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يعيد أحداث المراحل والترقيات لكل مُخرَج في المستودع، بدءًا من الأقدم، ليستطلعها CI/CD: إضافة مرحلة أو إزالتها، والترقية إلى مستودع آخر، والاستلام من مستودع. تحتوي الصفحة على limit حدثًا (من 1 إلى 100، والافتراضي 50)؛ احفظ آخر sequence وتابع بضبط after على قيمة next.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
after | الاستعلام | string | لا | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية |
limit | الاستعلام | string | لا | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية; At most 100. |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
items | مصفوفة من object | نعم | عدد العناصر: 100 كحد أقصى |
items[].sequence | string | نعم | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية |
items[].repository | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
items[].artifactId | string (uuid) | نعم | — |
items[].action | string | نعم | إحدى القيم: stage.added, stage.removed, promoted, received |
items[].stage | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$; يمكن أن يكون null |
items[].mode | string | نعم | إحدى القيم: copy, move, null; يمكن أن يكون null |
items[].peerRepository | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$; يمكن أن يكون null |
items[].peerArtifactId | string (uuid) | نعم | يمكن أن يكون null |
items[].actor | string | نعم | — |
items[].comment | string | نعم | عدد الأحرف: 1024 كحد أقصى; يمكن أن يكون null |
items[].occurredAt | string (date-time) | نعم | — |
next | string | نعم | يمكن أن يكون null |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/promotions" \
-H "Authorization: Bearer $ARKVORY_TOKEN"تحديد إصدار حزمة
GET HEAD /api/v1/repositories/{repository}/packages/resolve
الوصول: إذن المستودع: package.read; مفاتيح الملفات: read · إعادة المحاولة: آمن للتكرار (قراءة)
يختار إصدار UPack مسجّلًا واحدًا بالقواعد نفسها المتبعة في downloadPackageContent ويعيده دون البايتات: الإصدار ومعرّف المُخرَج وSHA-256 والحجم ووقت النشر والمراحل الحالية. name مطلوب، وgroup افتراضيًا المجموعة الجذرية؛ ويتم الاختيار بـ version مطابق تمامًا أو بنطاق SemVer range، ويمكن إضافة stage وprerelease=true وorder=promoted (يتطلب stage)؛ وبدون version وrange يكون الناتج أعلى إصدار مستقر. غياب أي تطابق هو 404؛ ونزّل النتيجة بمعرّف المُخرَج لتبقى على ذلك الإصدار.
المعلمات
| الاسم | الموضع | النوع | مطلوب | القواعد |
|---|---|---|---|---|
repository | المسار | string | نعم | يطابق النمط ^[a-z0-9][a-z0-9_-]{0,63}$ |
group | الاستعلام | string | لا | عدد الأحرف: 128 كحد أقصى |
name | الاستعلام | string | نعم | عدد الأحرف: 1–128 |
version | الاستعلام | string | لا | عدد الأحرف: 128 كحد أقصى; Exact version; excludes range. |
range | الاستعلام | string | لا | عدد الأحرف: 256 كحد أقصى; SemVer range: 1.2.3, ^1.2, ~1.2.3, 1.x, >=1.0.0 <2.0.0, a || b. |
stage | الاستعلام | string | لا | يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$; Only versions promoted to this stage. |
prerelease | الاستعلام | string | لا | إحدى القيم: true, false; Include prereleases. |
order | الاستعلام | string | لا | إحدى القيم: version, promoted; promoted picks the most recently staged version and requires stage. |
الاستجابة 200
| الحقل | النوع | مطلوب | القواعد |
|---|---|---|---|
group | string | نعم | — |
name | string | نعم | — |
version | string | نعم | — |
artifactId | string (uuid) | نعم | — |
sha256 | string | نعم | SHA-256: 64 رقمًا ست عشريًا بأحرف صغيرة |
size | string | نعم | عدد صحيح بأرقام عشرية، يُرسَل كسلسلة نصية |
publishedAt | string (date-time) | نعم | — |
stagedAt | string (date-time) | نعم | يمكن أن يكون null |
stages | مصفوفة من string | نعم | عدد العناصر: 16 كحد أقصى; بلا عناصر مكرّرة; كل عنصر: يطابق النمط ^[a-z0-9][a-z0-9_.-]{0,31}$ |
الاستجابات: 200, 400, 401, 403, 404, 409, 422, 503, 507
مثال
curl -X GET "$ARKVORY_URL/api/v1/repositories/$REPOSITORY/packages/resolve?name=$NAME" \
-H "Authorization: Bearer $ARKVORY_TOKEN"