مدخل: واجهة برمجة التطبيقات
واجهة برمجة تطبيقات أداة فحص DR: كل معامل وحقل، موضح
مرجع لشكل الطلب والحقلين اللذين يحملهما كل استجابة موثقة. تختلف الصفوف حسب الإجراء، لذا جرب استدعاءً واحدًا قبل التحليل.
الخدمة هي واجهة برمجة تطبيقات REST تعيد بيانات JSON. CORS مفتوح. يمكن لصفحة المتصفح استدعاؤها مباشرة. تبدأ المفاتيح بـ sk_ وتأتي من صفحة الحساب بعد تسجيل الدخول عبر Google.
عنوان URL الأساسي هو https://rankupedia.com/api.php. المصادقة باستخدام key=sk_... في سلسلة الاستعلام أو باستخدام رأس Authorization: Bearer sk_...، حسب تفضيل العميل الخاص بك. أربعة إجراءات لا تحتاج إلى ذلك: domain، overview، stats و suggest.
تكون أداة فحص DR مفيدة فقط بمجرد أن تتمكن من تحليل مخرجاتها. العينة أدناه هي أصغر حالة مفيدة، وتغطي الأقسام التي تليها الأجزاء التي يخطئ فيها الناس.
استدعاء واحد، معلق عليه
الإجراء المجاني overview. استبدل النطاق بنطاقك الخاص.
curl "https://rankupedia.com/api.php?action=overview&q=nytimes.com"
# authenticated listing, 100 rows per page:
curl -H "Authorization: Bearer sk_live_..." \
"https://rankupedia.com/api.php?action=refdomains&q=nytimes.com&per=100&page=1&order=desc"تشريح الطلب
سمِّ الهدف
قيمة q هي نطاق عاري مثل nytimes.com، بدون مخطط أو مسار.
أضف بيانات الاعتماد إذا كان الإجراء مدفوعًا
إما key في سلسلة الاستعلام أو رأس Bearer. تحافظ الرؤوس على المفاتيح بعيدًا عن سجلات الخادم وسجل المتصفح.
الصفحة والترتيب
تقسم page و per النتائج و sort مع order يرتبها. يتوقف الترقيم عند 50,000 صف.
تحضير قائمة النطاقات قبل الاستدعاء الأول
تبدأ العديد من النتائج الغريبة بالإدخال بدلاً من الخادم. نظف القائمة مرة واحدة، ثم أرسلها.
احذف أي شيء ليس نطاقًا عاريًا. يضيف العنوان المنسوخ مع المسار أحرف لا تتوقعها قيمة q، لذا احذف المخطط والمسار وأي شرطة مائلة في النهاية.
احذف المخطط والمسار
حوّل https://shop.example.org/blog/ إلى shop.example.org قبل الاستدعاء. تأخذ قيمة q نطاقًا عاريًا، لذا يُتخلص من المسار هنا بدلاً من إرساله.
تخفي جداول البيانات هذه التفاصيل داخل خلية. يؤدي تصفية سريعة للشرطتين المائلتين والنقطتين إلى التقاط معظمها.
حوّل الأسماء إلى أحرف صغيرة وأزل التكرارات
أسماء النطاقات ليست حساسة لحالة الأحرف، لذا فإن Example.COM و example.com يشاركان إلى هدف واحد. إرسال كليهما ينفد رصيد الاعتمادات مرتين مقابل إجابة واحدة.
أزل التكرارات قبل حساب الاستدعاءات. قائمة تحتوي على 2,100 اسم مع 300 تكرار تحتاج إلى استدعاءين bulk_dr خامًا، ولكن بعد إزالة التكرارات، تتسع الأسماء الفريدة البالغ عددها 1,800 في استدعاء واحد.
قرر بين الجذر والنطاق الفرعي
النطاق الفرعي مثل blog.example.org هو اسم خاص به في قائمتك. قرر حول أي منهما يتعلق سؤالك قبل إرسال أي شيء.
إذا كان السؤال يغطي الموقع بأكمله، أرسل الاسم الجذري. إذا كان يغطي نطاقًا فرعيًا واحدًا، اختبر ذلك الاسم بالضبط واقرأ الإجابة على أنها تنتمي إليه وحده.
اكتب القرار في ملاحظات المهمة، حتى في التشغيل التالي، ربما بواسطة شخص آخر، يتم تطبيق نفس القاعدة.
معاملات الاستعلام
| المعامل | المعنى | ملاحظات |
|---|---|---|
| action | العملية التي سيتم تشغيلها | مطلوب؛ انظر جدول التكاليف |
| q | نطاق الهدف | مثال: nytimes.com |
| key | مفتاح واجهة برمجة التطبيقات | أو استخدم رأس Bearer |
| page | رقم صفحة النتائج | الترقيم العميق محدود بـ 50,000 |
| per | صفوف لكل صفحة | يقبل من 10 إلى 5000؛ كل استدعاء هو شحنة واحدة، بأي عدد من الصفوف |
| sort | العمود لترتيب حسب | تعتمد الأعمدة المتاحة على الإجراء |
| order | asc أو desc | استخدمه مع sort |
| domains | قائمة لـ bulk_dr | الحد الأقصى 2,000 نطاق في كل مرة، عبر GET أو جسم POST |
التنقل عبر قائمة طويلة
تعيد إجراءات القوائم الصفوف في صفحات. معاملان يتحكمان في الشريحة: تختار page الشريحة، وتحدد per عدد الصفوف التي تحتويها. يقبل per قيمًا من 10 إلى 5000.
اختر حجم الصفحة أولاً. يقلل per الأكبر عدد الاستدعاءات، ويُحتسب الفوترة حسب الاستدعاءات وليس الصفوف.
الترتيب قبل الترقيم
يحدد sort و order الصفوف التي تظهر في الصفحة الأولى. اضبط كليهما في كل استدعاء في سلسلة، حتى تأتي كل صفحة من نفس الترتيب.
استخدم desc على عمود المقياس عندما تريد أقوى الصفوف أولاً، و asc عندما تبحث عن الأضعف. تعتمد أسماء الأعمدة المتاحة على الإجراء.
أكد الترتيب باختبار صغير لصفحتين قبل أن تثق بتشغيل طويل.
توقف عند حد 50,000 صف
يتوقف الترقيم العميق عند 50,000 صف. بعد ذلك، لا يعيد الاستدعاء أي شيء جديد، لذا فإن حلًا يستمر في الترقيم يهدر الاعتمادات.
حدّد السؤال أو قسّم المهمة إلى تشغيلات أصغر بدلاً من ذلك. عادةً ما يكون استعلامًا ثانيًا بهدف مختلف أنظف من صفحة أعمق.
حد العمق هو خاصية للقائمة، لذا ينطبق على كل عميل يستدعيها.
أنهِ الحلقة على صفحة قصيرة
توقف عندما تعيد الصفحة عدد صفوف أقل من per. هذا هو عادةً علامة نفاد القائمة.
اجمع هذا الاختبار مع فحص الرصيد في مدخل استكشاف الأخطاء، حتى تنتهي الحلقة في الصفحة الأخيرة أو عند انخفاض الرصيد، أيهما يحدث أولاً.
الحقول الموجودة في كل استجابة
ok
قيمة منطقية. تعني True اكتمال الاستدعاء. تعني False أنه لم يكتمل، ويخبرك وضع HTTP بالسبب.
_credits
يظهر في الاستدعاءات المصادق عليها. يبلغ عن تكلفة هذا الاستدعاء ورصيدك المتبقي من الاعتمادات، مما يتيح لك إيقاف حل قبل نفاد الرصيد.
أسماء الحقول على مستوى الصف لكل إجراء مرئية في استجابة حية. لا نعيد إنتاجها في هذا المدخل حتى لا تنحرف عن الخدمة.
اختبار استدعاء قبل كتابة حل
اختر نطاقًا تعرفه
اختر موقعًا يمكنك الحكم على ملفه الشخصي من صفحاته الخاصة. يجعلك نطاق تعرفه تلاحظ الأرقام الغريبة بسهولة.
أرسل استدعاءًا مجانيًا واحدًا
شغّل overview أو domain بدون مفتاح. تُظهر الاستجابة الشكل الحقيقي لـ JSON، وهو أكثر موثوقية من أي وصف، بما في ذلك هذا.
أرسل استدعاء مدفوعًا واحدًا بأصغر صفحة
استخدم per=10 على إجراء قائمة. سترى حقول الصف وقيمة _credits قبل التوسع.
اقرأ _credits، ثم وسّع
اضرب تكلفة استدعاء واحد بعدد الاستدعاءات في خطتك. إذا كان الإجمالي أكبر من الرصيد، قلص الخطة قبل بدء الحلقة.
قبل نشر عميل
- تحقق من ok قبل قراءة أي حقل آخر
- سجّل _credits في كل استدعاء
- عامل البيانات كلقطة شهرية
- عالج 401 و 402 بشكل منفصل، انظر مدخل استكشاف الأخطاء
- احتفظ بالمفتاح بعيدًا عن كود الواجهة الأمامية
ملاحظات حول الدفعات
يقبل الإجراء bulk_dr ما يصل إلى 2,000 نطاق في كل استدعاء. أرسلها كقيمة استعلام domains، أو كجسم POST عندما تكون القائمة طويلة جدًا لـ URL.
يأخذ compare ما يصل إلى 20 نطاقًا و intersect يأخذ من 2 إلى 10. يجيب Intersect على سؤال واحد: أي المواقع تربط بجميع النطاقات التي تحددها.
نظرًا لأن الفوترة لكل استدعاء، فإن الدفعات الأكبر دائمًا أرخص لكل صف. كما تفشل كوحدة واحدة. قسّم بحجم يمكنك إعادة المحاولة فيه.
يمكن وضع القوائم الطويلة في جسم POST. اقرأ ok قبل أي شيء آخر في الاستجابة، لأن الدفعة المرفقة لا تحتوي على صفوف يمكنك استخدامها.
قراءة JSON دون افتراضات
تنكسر المحللون على الحقول التي تتركها الاستجابة. الكود الذي يتوقع كل مفتاح في كل صف هش، وقد يوقف صف قصير مهمة بأكملها.
عامل الحقول المفقودة كشيء عادي
تعتمد حقول الصف على الإجراء، لذا يمكن أن يكون حقل موجود في قائمة واحدة غائبًا عن أخرى. امنح كل افتراضي افتراضي واستمر.
سجل أي حقل كان مفقودًا، وليس فقط أن شيئًا ما فشل. يظهر هذا السجل ما إذا كان المخطط أو الكود الخاص بك قد تغير.
احتفظ بالاستجابات الخام لعينة
احفظ JSON الخام للاستدعاءات الأولى في كل مهمة جديدة. عندما يبدو رقم ما خاطئًا لاحقًا، فإن النص المحفوظ يحسم السؤال أسرع من الذاكرة.
احفظ العينة مع تاريخها واسم الإجراء. يعني التحديث الشهري أن نفس الاستدعاء يمكن أن يعيد صفوفًا مختلفة الشهر المقبل.
الإجراءات حسب العائلة
| العائلة | الإجراءات | الاستخدام النموذجي |
|---|---|---|
| مجاني | domain, overview, stats, suggest | عمليات البحث السريعة والإكمال التلقائي |
| التقييم | bulk_dr, compare, dr_distribution | فحص القوائم ومجموعات الأقران |
| قائمة | refdomains, backlinks, anchors, toppages, anchor_cloud | مراجعة موقع واحد |
| بحث | search, keyword, intersect | إيجاد من يربط بنص لئمة معين أو إلى عدة منافسين |
تختلف أسماء الحقول على مستوى الصف حسب الإجراء ولا تُدرج هنا. اتصل بالنقطة النهائية بإجراء مجاني على نطاق تعرفه واقرأ JSON، وهو المصدر الوحيد الموثوق.
أسئلة المعاملات التي يطرحها المطورون
تغطي أربع أسئلة معاملات معظم الأسبوع الأول مع واجهة برمجة التطبيقات.
هل أحتاج إلى مفتاح لكل استدعاء؟
لا. لا تحتاج الإجراءات domain, overview, stats و suggest إلى مفتاح. تحتاج الإجراءات المدفوعة إلى واحد، يُرسل إما كمعامل key أو كرأس Bearer.
هل يمكنني إرسال المفتاح في URL؟
نعم، يعمل معامل key في سلسلة الاستعلام. يبقي الرأس المفتاح بعيدًا عن العنوان نفسه، وهو ما تفضله العديد من الفرق للسجلات والروابط المشتركة.
ماذا لو أردت per فوق 5000؟
النطاق الموثق هو من 10 إلى 5000. القيم خارج هذا النطاق تقع خارج ما يصفه هذا المدخل، لذا احتفظ بالقيمة داخل النطاق وكرر للصفحات.
هل يهم حالة الأحرف في q؟
أسماء النطاقات ليست حساسة لحالة الأحرف، لذا حول القيمة إلى أحرف صغيرة قبل إرسالها. يجعل تهجئة واحدة النتائج أسهل للمقارنة عبر التشغيلات.
