الانتقال إلى المحتوى الرئيسي

​
نظرة عامة

توفر عدة تطوير البرمجيات SDK الخاصة بـ Benzinga بلغة TypeScript/JavaScript واجهةً معيارية مكوّنة من وحدات وقائمة على الأحداث للتفاعل مع واجهات برمجة التطبيقات API من Benzinga. وبما أنها مكتوبة بلغة TypeScript، فإن الـ SDK تعمل بسلاسة في كلٍّ من بيئات المتصفح و Node.js، مع تقديم تنفيذات محسَّنة تتضمن التخزين المؤقت، والمقارنة العميقة، وغير ذلك من القدرات المتقدمة.

​
الميزات الرئيسية

  • دعم TypeScript - دعم كامل لأنواع (types) وواجهات (interfaces) TypeScript
  • عالمي - يعمل في متصفحات الويب وبيئات Node.js على حدٍّ سواء
  • هندسة معيارية - ثبّت فقط الوحدات (modules) التي تحتاجها
  • معتمد على الأحداث - أنماط برمجة تفاعلية للبيانات في الوقت الفعلي
  • ميزات متقدمة - تخزين مؤقت مدمج، مقارنة عميقة، وتحسينات في الأداء
  • حديث - صياغة ES6+ مع دعم async/await

​
المتطلبات

  • الإصدار 14 من Node.js أو أحدث

​
التثبيت

تتبع عدة تطوير البرمجيات SDK معمارية قائمة على الوحدات. ابدأ بتثبيت وحدة الجلسة الأساسية: 
npm install @benzinga/session
ثم قم بتثبيت وحدات إضافية حسب الحاجة: 
# مثال: تثبيت وحدات معينة
npm install @benzinga/calendar-data
npm install @benzinga/quotes
npm install @benzinga/news-data

​
البدء

​
إعداد الجلسة

توفر الوحدة @benzinga/session الأساس لعملية المصادقة مع واجهات برمجة التطبيقات API الخاصة بـ Benzinga. تعتمد جميع الوحدات الأخرى على كائن Session هذا. 
import { Session } from '@benzinga/session';

// تهيئة الجلسة باستخدام مفتاح API الخاص بك
const session = new Session({
  apiKey: 'YOUR_API_KEY'
});

​
خيارات التهيئة

يقبل كائن Session عدة خيارات تهيئة لتخصيص سلوكه: 
const session = new Session({
  apiKey: 'YOUR_API_KEY',
  environment: 'production', // أو 'sandbox'
  timeout: 30000,            // مهلة الطلب بالميلي ثانية
  // خيارات إعداد إضافية
});

​
المفاهيم الجوهرية

​
تصميم معياري

يتم تجميع كل نطاق من نطاقات واجهة برمجة التطبيقات API الخاصة بـ Benzinga كوحدة npm مستقلة. يتيح لك هذا:
  • تثبيت ما تحتاج إليه فقط
  • تقليل حجم الحزمة
  • الحفاظ على فصل واضح بين المسؤوليات
  • تحديث الوحدات بشكل مستقل

​
معمارية قائمة على الأحداث

تستخدم عدة تطوير البرمجيات SDK نمطًا قائمًا على الأحداث للتعامل مع تدفقات البيانات الفورية والتحديثات: 
// مثال: الاشتراك في تحديثات البيانات
dataManager.subscribe((data) => {
  console.log('New data received:', data);
});

// Example: Handle events
dataManager.on('update', (event) => {
  console.log('Data updated:', event);
});

​
التخزين المؤقت والأداء

يتضمن الـSDK آليات تخزين مؤقت مدمجة من أجل:
  • تقليل طلبات واجهة برمجة التطبيقات API غير الضرورية
  • تحسين زمن الاستجابة
  • تحسين استخدام النطاق الترددي
  • توفير بدائل للعمل في وضع عدم الاتصال

​
المقارنة العميقة

تتيح ميزات مقارنة البيانات المتقدمة ما يلي:
  • اكتشاف التغييرات في الكائنات المتداخلة
  • إدارة الحالة بكفاءة
  • مشغلات تحديث ذكية
  • تقليل مرات إعادة التصيير في تطبيقات واجهة المستخدم

​
الوحدات المتاحة

تم تنظيم عدة تطوير البرمجيات SDK في وحدات متخصصة تغطي مجالات مختلفة ضمن واجهة برمجة التطبيقات API:

​
الوحدات الأساسية

  • @benzinga/session - المصادقة وإدارة الجلسات (إلزامي)
  • @benzinga/calendar-data - أحداث calendar والإجراءات المؤسسية
  • @benzinga/news-data - المقالات الإخبارية وتحليلات السوق
  • @benzinga/quotes - الأسعار الفورية والمتأخرة
  • @benzinga/fundamentals - البيانات الأساسية والمالية للشركات

​
وحدات متخصصة

  • @benzinga/ratings - تقييمات المحللين والأسعار المستهدفة
  • @benzinga/options - نشاط الخيارات وتحليلاتها
  • @benzinga/transcripts - محاضر مكالمات الأرباح
  • @benzinga/logos - شعارات الشركات والعلامات التجارية
  • @benzinga/signals - إشارات التداول ومؤشراته

​
دعم TypeScript

عدة تطوير البرمجيات SDK مكتوبة بلغة TypeScript وتوفر تعريفات أنواع كاملة: 
import { Session } from '@benzinga/session';
import { CalendarData, DividendEvent } from '@benzinga/calendar-data';

// سيوفر TypeScript الإكمال التلقائي والتحقق من النوع
const session = new Session({ apiKey: 'YOUR_API_KEY' });
const calendar = new CalendarData(session);

// استدعاءات API آمنة من حيث النوع
const dividends: DividendEvent[] = await calendar.getDividends({
  dateFrom: '2024-01-01',
  dateTo: '2024-12-31',
  ticker: 'AAPL'
});

​
أمثلة على الاستخدام

​
جلب البيانات الأساسي

import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

// جلب أحدث الأخبار
const articles = await news.getNews({
  pageSize: 10,
  displayOutput: 'full'
});

console.log(articles);

​
تدفقات البيانات في الوقت الفعلي

import { Session } from '@benzinga/session';
import { QuoteStream } from '@benzinga/quotes';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const quoteStream = new QuoteStream(session);

// الاشتراك في عروض الأسعار الفورية
quoteStream.subscribe(['AAPL', 'MSFT', 'GOOGL'], (quote) => {
  console.log('Quote update:', quote);
});

// إلغاء الاشتراك عند الانتهاء
quoteStream.unsubscribe(['AAPL']);

​
أحداث التقويم

import { Session } from '@benzinga/session';
import { CalendarData } from '@benzinga/calendar-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const calendar = new CalendarData(session);

// الحصول على الأرباح القادمة
const earnings = await calendar.getEarnings({
  dateFrom: '2024-01-01',
  dateTo: '2024-01-31',
  importance: 3  // ذات الأهمية العالية فقط
});

// الحصول على توزيعات الأرباح
const dividends = await calendar.getDividends({
  ticker: 'AAPL'
});

​
الأساسيات المالية للشركة

import { Session } from '@benzinga/session';
import { Fundamentals } from '@benzinga/fundamentals';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const fundamentals = new Fundamentals(session);

// جلب الملف التعريفي للشركة
const profile = await fundamentals.getCompanyProfile('AAPL');

// جلب نسب التقييم
const valuationRatios = await fundamentals.getValuationRatios('AAPL');

// جلب القوائم المالية
const financials = await fundamentals.getFinancials('AAPL');

​
الاستخدام في المتصفح

تعمل عدة تطوير البرمجيات SDK في بيئات المتصفح مع أدوات التجميع مثل Webpack وRollup وVite: 
// في تطبيق React أو Vue أو Angular الخاص بك
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

export function NewsComponent() {
  const session = new Session({ apiKey: process.env.BENZINGA_API_KEY });
  const news = new NewsData(session);

  // استخدم في منطق المكون الخاص بك
  useEffect(() => {
    news.getNews({ pageSize: 5 }).then(articles => {
      setNewsData(articles);
    });
  }, []);
}

​
معالجة الأخطاء

عالِج الأخطاء بسلاسة باستخدام كتل try/catch: 
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

try {
  const articles = await news.getNews({ pageSize: 10 });
  console.log(articles);
} catch (error) {
  if (error.code === 'UNAUTHORIZED') {
    console.error('مفتاح API غير صالح');
  } else if (error.code === 'RATE_LIMIT') {
    console.error('تم تجاوز حد المعدل');
  } else {
    console.error('حدث خطأ:', error.message);
  }
}
التعامل بكفاءة مع النتائج المقسَّمة إلى صفحات: 
import { Session } from '@benzinga/session';
import { NewsData } from '@benzinga/news-data';

const session = new Session({ apiKey: 'YOUR_API_KEY' });
const news = new NewsData(session);

// جلب صفحات متعددة
let page = 0;
let allArticles = [];

while (page < 5) {
  const articles = await news.getNews({
    page: page,
    pageSize: 100
  });

  if (articles.length === 0) break;

  allArticles = allArticles.concat(articles);
  page++;
}

console.log(`Fetched ${allArticles.length} articles`);

​
استراتيجية التخزين المؤقت

استخدم ميزة التخزين المؤقت المدمجة لتحسين الأداء: 
import { Session } from '@benzinga/session';
import { CalendarData } from '@benzinga/calendar-data';

const session = new Session({
  apiKey: 'YOUR_API_KEY',
  cache: {
    enabled: true,
    ttl: 300000  // التخزين المؤقت لمدة 5 دقائق
  }
});

const calendar = new CalendarData(session);

// الاستدعاء الأول يتصل بواجهة برمجة التطبيقات API
const earnings1 = await calendar.getEarnings({ ticker: 'AAPL' });

// الاستدعاء الثاني يستخدم البيانات المخزنة مؤقتاً (إذا كانت ضمن TTL)
const earnings2 = await calendar.getEarnings({ ticker: 'AAPL' });

​
أفضل الممارسات

​
1. إعادة استخدام كائنات الجلسة

أنشئ مثيلًا واحدًا للجلسة وأعد استخدامه في جميع أنحاء تطبيقك: 
// session.ts
export const globalSession = new Session({ apiKey: process.env.BENZINGA_API_KEY });

// في ملفات أخرى
import { globalSession } from './session';
const news = new NewsData(globalSession);

​
2. متغيرات البيئة

خزِّن مفاتيح واجهة برمجة التطبيقات API بأمان في متغيرات البيئة: 
// ملف .env
BENZINGA_API_KEY=your_api_key_here

// في الكود
const session = new Session({
  apiKey: process.env.BENZINGA_API_KEY
});

​
3. سلامة الأنواع (Type Safety)

استفد من TypeScript لضمان تفاعلات آمنة من ناحية الأنواع مع واجهة برمجة التطبيقات API: 
import type { NewsArticle, NewsParams } from '@benzinga/news-data';

const params: NewsParams = {
  pageSize: 10,
  displayOutput: 'full',
  ticker: 'AAPL'
};

const articles: NewsArticle[] = await news.getNews(params);

​
4. حدود الأخطاء

طبِّق حدود الأخطاء في بيئة الإنتاج: 
const safeApiCall = async (fn: () => Promise<any>) => {
  try {
    return await fn();
  } catch (error) {
    console.error('API Error:', error);
    // تسجيل الخطأ في خدمة تتبع الأخطاء
    return null;
  }
};

const articles = await safeApiCall(() => news.getNews({ pageSize: 10 }));

​
الموارد

​
توثيق الوحدات

للحصول على توثيق مفصل للوحدات المحددة، راجع ملفات README الخاصة بكل حزمة:
  • @benzinga/session - المصادقة الأساسية والإعدادات
  • @benzinga/calendar-data - واجهة برمجة التطبيقات API لأحداث calendar
  • @benzinga/news-data - واجهة برمجة التطبيقات API للأخبار والمقالات
  • @benzinga/quotes - واجهة برمجة التطبيقات API للأسعار الآنية
  • @benzinga/fundamentals - واجهة برمجة التطبيقات API للأساسيات المالية والبيانات المالية

​
الدعم

للدعم الفني ولطلب مفتاح واجهة برمجة التطبيقات API، تواصل مع Benzinga عبر cloud.benzinga.com.

​
المساهمة

عدة تطوير البرمجيات SDK من Benzinga لـ JavaScript مفتوحة المصدر. نرحّب بالمساهمات! زُر مستودع GitHub لمزيد من المعلومات.