الجداول

حوّل الروابط في جدول Google Sheets كامل أو في مصنف مرفوع باستخدام رمز bearer الخاص بحسابك. يكون الناتج دائمًا بصيغة .xlsx، حتى عندما يكون الإدخال CSV. تُستبدل الروابط في أماكنها، وتُنسب إلى حسابك مع القيمتين الاختياريتين campaign وlabel كما هو موضح في الروابط.

إدخال Google Sheetsنسخ رابط القسم

أرسل رابط Google Sheets يستطيع NinjaBuy قراءته. يقرأ التحويل جميع علامات التبويب، لا المعاينة المعروضة فقط، ويحفظ لقطة ثابتة لهذه المهمة.

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://docs.google.com/spreadsheets/d/SHEET_ID/edit","campaign":"spring-haul","label":"finds"}'

إدخال XLSX أو CSVنسخ رابط القسم

احجز عملية رفع أولًا. يجب أن ينتهي filename بـ .xlsx أو .csv وأن يتكون من 1 إلى 255 حرفًا بعد حذف المسافات من طرفيه. أما bytes فهو حجم الملف الدقيق بالبايت، من 1 إلى 20,971,520.

curl -sS https://www.ninjabuy.com/api/v1/uploads \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"filename":"finds.xlsx","bytes":12345}'

تحتوي الاستجابة 201 على upload_id، وurl موقّع لطلب PUT، وexpires_at (بالمللي ثانية منذ بداية حقبة Unix)، وmax_bytes، وrequest_id. تنتهي صلاحية الحجز بعد 15 دقيقة. أرسل الملف الخام بطلب PUT إلى الرابط المُعاد، ثم أرسل معرّف الرفع الخاص به:

curl --fail-with-body -X PUT "$UPLOAD_URL" \
  --data-binary @finds.xlsx

curl -sS -D sheet-headers.txt https://www.ninjabuy.com/api/v1/sheets \
  -H "Authorization: Bearer $NINJABUY_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"upload_id":"UPLOAD_ID","campaign":"spring-haul","label":"finds"}'

يتبع طلب PUT المباشر عقد الاستجابة الخاص بخدمة التخزين. يتحقق NinjaBuy من البايتات المرفوعة عند إرسالك طلب التحويل. تُعيد معرّفات الرفع غير المعروفة أو التابعة لحسابات أخرى 404. يجب أن يطابق الكائن المخزَّن عدد البايتات المُصرَّح به؛ فالكائن الأكبر من الحجم المُصرَّح به أو من الحد الأقصى يُعيد 413 upload-too-large، والكائن الأصغر (المقتطع) يُعيد 422 invalid-workbook مع شرح لعدم تطابق عدد البايتات. تجري هذه الفحوص قبل التنزيل، وتنطبق أيضًا إذا تغيّرت البايتات بعد فحص البيانات الوصفية. تُحذف الملفات الخام المرفوضة، وتُحذف الملفات الخام المقبولة بمجرد تسجيل لقطتها التي جرى التحقق منها.

أرسل مصدرًا واحدًا فقط: url أو upload_id. يقبل كلاهما campaign وlabel الاختياريين، ولا حاجة إلى الحقل async. يقبل مسارا POST كلاهما Idempotency-Key، ويستهلك كل منهما خانة واحدة من نافذة الإنشاء المشتركة البالغة 30 طلبًا في الدقيقة. لا تستهلك تحويلات الروابط الفرعية أي خانات إضافية.

المهمة والتنزيلنسخ رابط القسم

يُعيد إرسال الجدول 202 مع Location: /api/v1/jobs/JOB_ID وRetry-After: 5 وهذا المحتوى:

{
  "job": {
    "id": "JOB_ID",
    "kind": "sheet_conversion",
    "status": "queued",
    "poll_after_seconds": 5
  },
  "request_id": "REQUEST_ID"
}

استعلم عن المهام برمز الحساب نفسه حتى تصل إلى done أو failed، مع الالتزام بـ poll_after_seconds. يحتوي job.result المكتمل على kind: "sheet_conversion" وcounts وdownload_url موقّع صالح لمدة 15 دقيقة. استعلم مرة أخرى للحصول على توقيع تنزيل جديد. تحتوي المهمة الفاشلة على error ولا يتوفر لها تنزيل جزئي.

بالنسبة إلى جدول Google Sheets، قد يتضمن job.result أيضًا copy_url، وهو رابط للعرض فقط إلى نسخة مطابقة على Google Sheets تحتوي روابطك في أماكنها؛ ويستطيع أي شخص لديه الرابط الاحتفاظ بنسخته الخاصة عبر ملف ← إنشاء نسخة. يسرد copy_notes ما ينبغي أن يعرفه قارئ تلك النسخة، مثل أن الصور المُنشأة بـ =IMAGE() تحتاج إلى نقرة واحدة على السماح بالوصول في نسخته. يظل download_url يُعيد ملف XLSX. يعطي copy_counts الأعداد نفسها للنسخة؛ وعندما يتعذر إنشاء ملف XLSX، يحتفظ الناتج بـ copy_url ولا يحتوي على download_url، ويوضح copy_notes السبب. يسرد download_notes، سطرًا بسطر، ما لا يستطيع ملف XLSX استيعابه من الجدول، مثل الرسوم البيانية أو رابط ثانٍ في خلية.

تُحفظ اللقطات وملفات النتائج لمدة سبعة أيام بعد انتهاء المهمة أو فشلها. بعد التنظيف، تبقى المهمة قابلة للقراءة مع حالتها وأعدادها، ويُحذف job.result.download_url. تبقى اللقطات المشتركة ما دامت مهمة أخرى تحتاج إليها. تُحذف الملفات الخام المتروكة بعد ساعة من انتهاء صلاحية حجز الرفع؛ والرفع الذي جرى التحقق منه ولم يبدأ أي مهمة يفقد لقطته بعد سبعة أيام من انتهاء صلاحية الحجز. يعمل التنظيف كل ساعة.

تتحقق التغطية من المعادلة links_found = converted + sum(left_by_host) + unresolved. تبقى روابط مواقع التواصل الاجتماعي وروابط Google Sheets والتنقل داخل المصنف نفسه وروابط NinjaBuy الموجودة دون تغيير. يجب أن يتلقى كل مرشح للتحويل إجابة قبل كتابة الناتج؛ وتؤدي الإجابات المفقودة إلى فشل المهمة.

الحفاظ على المصنفنسخ رابط القسم

يحافظ الناتج على التنسيقات والخلايا المدمجة وأحجام الصفوف والأعمدة والصور كما تمثّلها الشبكة المحلَّلة. تبقى مقاطع النص المنسَّق في الخلايا التي لا تحتوي على ارتباط تشعبي للخلية؛ أما الخلايا المرتبطة فتستخدم تسمية نصية واحدة وارتباطًا تشعبيًا واحدًا. إنه مصنف مُعاد إنشاؤه من جديد: لا يُحتفظ بالرسوم البيانية ووحدات الماكرو والميزات الأخرى الواقعة خارج تلك الشبكة.

يدعم XLSX ارتباطًا تشعبيًا واحدًا لكل خلية. يستبدل التحويل الروابط في أماكنها بدلًا من إضافة رابط ثانٍ بجانبها. والخلية التي تحتوي على وجهتين مختلفتين أو أكثر لروابط غير صور تحتفظ بالأولى ارتباطًا تشعبيًا لها وتسرد البقية في ملاحظة الخلية، فلا تضيع أي وجهة.

الحدودنسخ رابط القسم

يؤدي تجاوز أي حد من حدود التحليل أو الكتابة إلى فشل صريح. راجع الأخطاء بخصوص invalid-workbook وupload-expired وupload-too-large.