تخطَّ إلى المحتوى

الرفع من عنوان

POST /public/v1/upload-from-url

يجلب الوسائط من عنوان ويخزنها في مكتبة الوسائط، معيدًا صف الوسائط نفسه الذي يعيده رفع ملف. مفيد حين يكون الأصل موجودًا في مكان عام أصلًا ولا تفضل تنزيله وإعادة رفعه.

إن كنت تفعل ذلك من التطبيق، فراجع مكتبة الوسائط. وهذه العملية متاحة أيضًا بالأداة uploadFromUrlTool في خادم MCP من شارك، ولا يقابلها أمر في أداة CLI.

الحقل مطلوب الوصف
url نعم عنوان HTTPS عام ينتهي بامتداد مقبول.
Terminal window
curl -X POST https://dash.sharek.app/api/public/v1/upload-from-url \
-H "Authorization: your-api-key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://media.example.com/launch.png" }'
{
"id": "media-id",
"name": "a1b2c3d4e5.png",
"originalName": null,
"path": "https://media.example.com/a1b2c3d4e5.png",
"thumbnail": null,
"alt": null,
"status": "ready"
}

ويخزن شارك الملف باسم مولد بالامتداد المأخوذ من النوع المكتشف، فاسم الملف الموجود في العنوان لا يحفظ.

وقيمة status هي ready، فيمكن إدراج الملف في منشور فورًا. ولقراءتها مجددًا لاحقًا، استدع GET /public/v1/media/:id/status بمعرف الوسائط id، فيعيد id وpath وstatus لذلك الملف، أو 404 Media not found حين لا يكون المعرف في مكتبتك.

ويبقى الملف في مكتبة الوسائط. ولإعادة استخدام ملف رفعته من قبل في منشور لاحق، يعيد سرد الوسائط قيمتي id وpath الخاصتين به مرة أخرى، فلا حاجة إلى جلب العنوان مرتين.

ما يجب أن يستوفيه العنوان

Section titled “ما يجب أن يستوفيه العنوان”

يفحص العنوان قبل جلب أي شيء، ويفحص المحتوى بعد ذلك. وكل هذه تسري:

  1. يجب أن ينتهي المسار بامتداد مقبول: .png أو .jpg أو .jpeg أو .gif أو .webp أو .mp4. ونص الاستعلام يتجاهل في هذا الفحص، فـ .../photo.png?v=2 يمر.
  2. HTTPS، ومضيف عام. فالعناوين التي تشير إلى عناوين شبكة داخلية أو خاصة ترفض، وهو ما يستبعد الجلب من localhost أو من نطاق خاص.
  3. يجب أن تطابق البايتات نوعًا مقبولًا، يكتشف بعد التنزيل تمامًا كما في الرفع المباشر. فعنوان .png يقدم HTML يرفض.
  4. حدود الحجم تسري: 10 MB للصور، و1 GB للفيديو. ويفحص شارك Content-Length المعلن قبل التنزيل والحجم الحقيقي بعده، فالترويسة الكاذبة لا تمر.
الاستجابة المعنى
400 تحقق من الحقول أخفق url في فحص الامتداد أو فحص HTTPS العام، فلم يجلب شيء.
400 {"msg": "Failed to fetch URL"} تعذر الوصول إلى المضيف، أو أجاب بحالة غير ناجحة.
400 {"msg": "Unsupported file type."} تم تنزيله بنجاح، لكن البايتات ليست نوعًا مقبولًا.
400 {"msg": "Failed to read file"} تعذر على شارك قراءة بداية الملف الذي تم تنزيله لاكتشاف نوعه.
400 {"msg": "File is too large."} فوق الحد الأقصى لنوعه.