واجهة برمجة التطبيقات لبيانات تعريف URL: إنشاء معاينات الارتباط مثل Slack في مكالمة واحدة

يقوم المستخدم بلصق عنوان URL في تطبيق الدردشة الخاص بك. تريد إظهار بطاقة معاينة غنية بعنوان الصفحة، الوصف والصورة المصغرة؛ نفس عرض البطاقة Slack وDiscord وiMessage. يمكنك ذلك قم بإحضار الصفحة وتحليل HTML واستخرج علامات Open Graph بنفسك. أو يمكنك إرسال واحدة طلب ما بعد.

البوتوي /v1/url-metadata تقوم نقطة النهاية بجلب أي عنوان URL، وتقرأه <meta> العلامات، وإرجاع JSON منظم: عنوان OG، وصف OG، صورة OG، بيانات بطاقة Twitter والأيقونة المفضلة وعنوان URL الأساسي واللغة والمزيد. مكالمة واحدة تحل محل الجلب، محلل HTML والمنطق الاحتياطي.

نقطة النهاية

curl -X POST https://api.botoi.com/v1/url-metadata \\
  -H "Content-Type: application/json" \\
  -d '{ "url": "https://github.com/anthropics/claude-code" }'

إجابة:

{
  "success": true,
  "data": {
    "url": "https://github.com/anthropics/claude-code",
    "status": 200,
    "content_type": "text/html",
    "title": "anthropics/claude-code: Claude Code is an agentic coding tool",
    "description": "Claude Code is an agentic coding tool that lives in your terminal",
    "og": {
      "title": "anthropics/claude-code",
      "description": "Claude Code is an agentic coding tool that lives in your terminal",
      "image": "https://opengraph.githubassets.com/1/anthropics/claude-code",
      "type": "object",
      "url": "https://github.com/anthropics/claude-code",
      "site_name": "GitHub"
    },
    "twitter": {
      "card": "summary_large_image",
      "title": "anthropics/claude-code",
      "description": "Claude Code is an agentic coding tool that lives in your terminal",
      "image": null
    },
    "favicon": "https://github.com/favicon.ico",
    "canonical": "https://github.com/anthropics/claude-code",
    "language": "en",
    "author": null,
    "keywords": [],
    "theme_color": null
  }
}

تمنحك الاستجابة كل ما تحتاجه لعرض بطاقة معاينة الرابط. ال og يحتوي الكائن على علامات Open Graph التي يقرأها Slack وDiscord. ال twitter يحتوي الكائن على علامات Twitter Card. عندما تقوم الصفحة بتعيين كليهما، تحصل على على حد سواء. عندما لا تقوم الصفحة بتعيين أي منهما، فستظل تحصل على HTML title و description كاحتياط.

إنشاء مكون معاينة رابط تطبيق الدردشة

يأخذ مكون Preact عنوان URL، ويستدعي واجهة برمجة التطبيقات (API)، ويعرض بطاقة تحتوي على صورة OG، والعنوان، الوصف واسم الموقع. يعود إلى عنوان HTML عندما تكون علامات OG مفقودة.

import { useState, useEffect } from "preact/hooks";

interface LinkPreview {
  title: string | null;
  description: string | null;
  image: string | null;
  favicon: string | null;
  url: string;
  siteName: string | null;
}

function useLinkPreview(url: string) {
  const [preview, setPreview] = useState<LinkPreview | null>(null);
  const [loading, setLoading] = useState(false);

  useEffect(() => {
    if (!url) return;
    setLoading(true);

    fetch("https://api.botoi.com/v1/url-metadata", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ url }),
    })
      .then((res) => res.json())
      .then(({ data }) => {
        setPreview({
          title: data.og?.title || data.title,
          description: data.og?.description || data.description,
          image: data.og?.image || null,
          favicon: data.favicon,
          url: data.canonical || url,
          siteName: data.og?.site_name || null,
        });
      })
      .catch(() => setPreview(null))
      .finally(() => setLoading(false));
  }, [url]);

  return { preview, loading };
}

function LinkPreviewCard({ url }: { url: string }) {
  const { preview, loading } = useLinkPreview(url);

  if (loading) {
    return (
      <div class="rounded-lg border border-gray-200 p-4 animate-pulse">
        <div class="h-4 bg-gray-100 rounded w-3/4 mb-2"></div>
        <div class="h-3 bg-gray-100 rounded w-full"></div>
      </div>
    );
  }

  if (!preview) return null;

  return (
    <a
      href={preview.url}
      target="_blank"
      rel="noopener noreferrer"
      class="block rounded-lg border border-gray-200 overflow-hidden
             hover:border-gray-400 transition-colors no-underline"
    >
      {preview.image && (
        <img
          src={preview.image}
          alt=""
          class="w-full h-40 object-cover"
        />
      )}
      <div class="p-4">
        <div class="flex items-center gap-2 mb-2">
          {preview.favicon && (
            <img src={preview.favicon} alt="" class="w-4 h-4" />
          )}
          <span class="text-xs text-gray-500">
            {preview.siteName || new URL(preview.url).hostname}
          </span>
        </div>
        <p class="font-semibold text-sm text-gray-900 mb-1">
          {preview.title}
        </p>
        <p class="text-xs text-gray-600 line-clamp-2">
          {preview.description}
        </p>
      </div>
    </a>
  );
}

ال useLinkPreview يعالج الخطاف عملية الجلب ويعين استجابة واجهة برمجة التطبيقات (API) إلى ملف مسطح كائن يمكن أن تستهلكه واجهة المستخدم الخاصة بك. السلسلة الاحتياطية (data.og?.title || data.title) يعني أن لديك دائمًا شيئًا ما لعرضه، حتى عندما لا تحتوي الصفحة على أي علامات OG. المكون يعرض هيكل التحميل أثناء تشغيل استدعاء واجهة برمجة التطبيقات (API)، ثم يقوم بالتبديل في بطاقة المعاينة.

الملء التلقائي لبيانات تعريف تحسين محركات البحث (SEO) في نظام إدارة المحتوى (CMS).

يقوم محررو المحتوى بلصق عناوين URL المرجعية عند كتابة المقالات. بدلًا من جعلها نسخًا ولصقًا العنوان والوصف يدويًا، يستطيع نظام إدارة المحتوى (CMS) الخاص بك سحب تلك البيانات من عنوان URL وملء الملف مسبقًا حقول تحسين محركات البحث.

async function autoFillSeoFields(referenceUrl: string) {
  const res = await fetch("https://api.botoi.com/v1/url-metadata", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: \`Bearer \${process.env.BOTOI_API_KEY}\`,
    },
    body: JSON.stringify({ url: referenceUrl }),
  });

  const { data } = await res.json();

  return {
    seoTitle: data.og?.title || data.title || "",
    seoDescription: data.og?.description || data.description || "",
    ogImage: data.og?.image || "",
    canonical: data.canonical || referenceUrl,
    favicon: data.favicon || "",
  };
}

// Usage in a CMS admin panel
const fields = await autoFillSeoFields("https://stripe.com/docs/payments");
// fields.seoTitle       → "Payments | Stripe Documentation"
// fields.seoDescription → "Accept payments online..."
// fields.ogImage        → "https://images.stripe.com/..."

عندما يقوم أحد المحررين بلصق عنوان URL في الحقل "المرجع"، يستدعي نظام إدارة المحتوى (CMS). autoFillSeoFields, يملأ عنوان SEO والوصف ومدخلات صورة OG، ويتيح للمحرر إمكانية التعديل من هناك. يعمل نفس الأسلوب مع مديري الإشارات المرجعية وتطبيقات القراءة اللاحقة وأدوات wiki الداخلية التي إنشاء بطاقات تلقائيًا من الروابط الملصقة.

وظيفة Node.js مع المهلة ومعالجة الأخطاء

في الإنتاج، تريد مهلة حتى لا تمنع الصفحة المستهدفة البطيئة طلبك إلى أجل غير مسمى. تقوم هذه الوظيفة بتغليف استدعاء واجهة برمجة التطبيقات (API) خلال 5 ثوانٍ AbortController مهلة و يعود null على الفشل بدلا من الرمي.

async function getLinkPreview(url: string) {
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 5000);

  try {
    const res = await fetch("https://api.botoi.com/v1/url-metadata", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Authorization: \`Bearer \${process.env.BOTOI_API_KEY}\`,
      },
      body: JSON.stringify({ url }),
      signal: controller.signal,
    });

    if (!res.ok) {
      throw new Error(\`API returned \${res.status}\`);
    }

    const { success, data } = await res.json();

    if (!success) {
      return null;
    }

    return {
      title: data.og?.title || data.title,
      description: data.og?.description || data.description,
      image: data.og?.image,
      favicon: data.favicon,
      siteName: data.og?.site_name,
      canonical: data.canonical,
      twitterCard: data.twitter?.card,
    };
  } catch (err) {
    console.error(\`Failed to fetch preview for \${url}:\`, err);
    return null;
  } finally {
    clearTimeout(timeout);
  }
}

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

التعامل مع حالات الحافة

لا يتعاون كل عنوان URL. بعض الصفحات لا تحتوي على علامات OG. البعض وراء سلاسل إعادة التوجيه. بعض يستغرق 10 ثانية للرد. وإليك كيفية التعامل مع كل حالة.

// 1. Pages with no OG tags: fall back to title + description
const preview = await getLinkPreview(url);
const displayTitle = preview?.title || "Untitled page";
const displayDesc = preview?.description || url;
const displayImage = preview?.image || "/fallback-thumbnail.png";

// 2. Detect redirects by comparing input URL to canonical
const inputUrl = "https://bit.ly/3xYzAbc";
const result = await getLinkPreview(inputUrl);
if (result?.canonical !== inputUrl) {
  console.log(\`Redirected to: \${result?.canonical}\`);
}

// 3. Batch multiple URLs with Promise.allSettled
const urls = [
  "https://github.com",
  "https://stripe.com",
  "https://vercel.com",
];

const previews = await Promise.allSettled(
  urls.map((u) => getLinkPreview(u))
);

const results = previews.map((p, i) => ({
  url: urls[i],
  preview: p.status === "fulfilled" ? p.value : null,
}));

لا والعلامات: العودة إلى title و description. إذا تلك فارغة أيضًا، قم بعرض عنوان URL الأولي. إظهار صورة العنصر النائب عندما og.image فارغة.

عمليات إعادة التوجيه: تتبع واجهة برمجة التطبيقات عمليات إعادة التوجيه وتعيد البيانات الوصفية من الصفحة النهائية. قارن عنوان URL للإدخال مع canonical لاكتشاف وقت حدوث إعادة التوجيه.

الصفحات البطيئة: اضبط مهلة على جانبك (5 ثوانٍ مناسبة لمعظم الحالات). ال واجهة برمجة التطبيقات نفسها لها مهلة داخلية، ولكن يجب عليك فرض مهلة خاصة بك حتى لا يحدث ذلك للهدف البطيء تعطيل تجربة المستخدم الخاصة بك.

جلب الدفعة: يستخدم Promise.allSettled لجلب معاينات ل عناوين URL متعددة بالتوازي. عودة الطلبات الفاشلة null دون حجب الباقي.

النقاط الرئيسية

• POST /v1/url-metadata إرجاع علامات OG، وعلامات بطاقة Twitter، والأيقونة المفضلة، والكنسي عنوان URL واللغة والكلمات الرئيسية في استجابة JSON واحدة.
• تعكس الاستجابة البيانات التي يستخدمها Slack وDiscord وiMessage لعرض معاينات الارتباط. أنت الحصول على نفس الحقول دون كتابة محلل HTML.
• يعمل الوصول المجهول بمعدل 5 طلبات في الدقيقة بدون مفتاح API. كفى للتنمية والتطبيقات ذات حركة المرور المنخفضة.
• العودة إلى title و description عندما تكون علامات OG مفقودة. تقوم واجهة برمجة التطبيقات (API) دائمًا بإرجاع هذه البيانات من HTML <head> عندما تكون موجودة.
• لاستخدام الإنتاج، قم بإضافة مهلة، ونتائج ذاكرة التخزين المؤقت حسب عنوان URL، والتعامل معها null الردود برشاقة. تحقق من مستندات API للحصول على مرجع المعلمة الكامل.