الاتصال بقاعدة بيانات باستخدام Azure Static Web Apps (معاينة)

هام

إشعار التقاعد: ينتهي برنامج اتصالات قواعد البيانات لتطبيقات الويب الثابتة في 30 نوفمبر 2025. انتقل الآن لتجنب الاضطراب.

تتيح لك ميزة الاتصال بقاعدة بيانات تطبيقات الويب الثابتة في Azure الوصول إلى قاعدة البيانات من تطبيق الويب الثابت دون الحاجة لكتابة كود مخصص على جانب الخادم.

بمجرد إنشاء اتصال بين تطبيق الويب وقاعدة البيانات، يمكنك التلاعب بالبيانات بدعم كامل لعمليات CRUD، والتفويض المدمج، والعلاقات.

استنادا إلى منشئ واجهة برمجة تطبيقات البيانات، تأخذ تطبيقات الويب الثابتة في Azure طلبات REST و GraphQL وتحولها إلى استعلامات قواعد بيانات.

تشمل الميزات المدعومة باتصالات قواعد البيانات:

الميزة	الوصف
الأمن المتكامل	تكامل مدمج مع نموذج أمان المصادقة والتفويض في Azure Static Web Apps. نفس الأمان القائم على الأدوار المستخدم لتأمين المسارات متاح لنقاط نهاية واجهات برمجة التطبيقات.
عمليات كاملة قائمة على CRUD	راجع الدروس التعليمية ل Azure Cosmos DB، Azure SQL أو MySQL، أو PostgreSQL كمثال حول كيفية التعامل مع البيانات في تطبيقك.
يدعم SQL و NoSQL	يمكنك استخدام قواعد البيانات العلائقية وقواعد البيانات المستندية كقاعدة بيانات لتطبيقك.
بنية بدون خادم	تتراكم الاتصالات من 0 إلى 1 عامل (أثناء المعاينة).
علاقات قواعد البيانات	مدعوم فقط عبر نقطة نهاية GraphQL.
دعم CLI	قم بالتطوير محليا باستخدام واجهة برمجة التطبيقات الثابتة (CLI). استخدم الخيار --data-api-location للتعامل مع طلبات واجهات برمجة التطبيقات للبيانات أثناء التطوير تماما كما تتم في السحابة.

قواعد البيانات المدعومة

يوضح الجدول التالي دعم قواعد البيانات العلائقية المختلفة وقواعد بيانات NoSQL.

Name	النوع	الوصف	REST	GraphQL
Azure Cosmos DB	Standard	منصة قواعد بيانات موزعة عالميا لكل من NoSQL وقواعد البيانات العلائقية بأي حجم. بالإضافة إلى التكوين القياسي، هناك حاجة إلىgql ملف مخطط لنقاط نهاية GraphQL.		✔
عنوان SQL لـ Azure	Standard	عائلة من المنتجات المدارة والآمنة والذكية التي تستخدم محرك قاعدة بيانات SQL Server في سحابة Azure.	✔	✔
قاعدة بيانات Azure ل MySQL	مرونة	خدمة قاعدة بيانات علائقية في سحابة مايكروسوفت بناء على إصدار مجتمع MySQL	✔	✔
قاعدة بيانات Azure ل PostgreSQL	مرونة	قاعدة بيانات PostgreSQL المدارة بالكامل كخدمة تتعامل مع أعباء العمل الحرجة بأداء متوقع وقابلية توسع ديناميكية.	✔	✔
Azure Database for PostgreSQL (single)	فردي	قاعدة بيانات PostgreSQL مدارة بالكامل.	✔	✔

يمكنك استخدام أنواع الاتصال التالية للوصول إلى قاعدة البيانات:

• سلسلة الاتصال
• الهوية المُدارة التي يُعيّنها المستخدم
• الهوية المدارة المعينة من النظام

موقع نقطة النهاية

الوصول إلى نقاط نهاية البيانات متاح خارج /data-api المسار.

يوضح لك الجدول التالي كيفية توجيه الطلبات إلى أجزاء مختلفة من تطبيق ويب ثابت:

المسار	الوصف
example.com/api/*	وظائف API
example.com/data-api/*	نقاط نهاية اتصال قاعدة البيانات التي تدعم طلبات REST و GraphQL.
example.com/*	المحتوى الثابت

عند تكوين اتصالات قواعد البيانات على موقعك، يمكنك تكوين لاحقة REST أو GraphQL للمسار /data-api/* . البادئة /data-api هي تقليد لتطبيقات الويب الثابتة ولا يمكن تغييرها.

التكوين

هناك خطوتان لتكوين اتصال قاعدة البيانات في تطبيقات الويب الثابتة. تحتاج إلى توصيل قاعدة بياناتك بتطبيق الويب الثابت في بوابة Azure، وتحديث ملف إعدادات اتصالات قاعدة البيانات.

انظر تكوين اتصال قاعدة البيانات في Azure Static Web Apps لمزيد من التفاصيل.

التنمية المحلية

تتضمن تطبيقات الويب الثابتة في Azure (SWA CLI) دعم العمل مع اتصالات قواعد البيانات أثناء التطوير المحلي.

يقوم ملف CLI بتفعيل نقطة النهاية المحلية /data-api ، ويرسل الطلبات من المنفذ 4280 إلى المنفذ المناسب للوصول إلى قاعدة البيانات.

إليك أمر نموذجي يبدأ واجهة سطر SWA باتصال قاعدة بيانات:

swa start ./src --data-api-location swa-db-connections

هذا الأمر يبدأ واجهة القيادة SWA في مجلد src . يخبر الخيار --data-api-location قائد الأوامر أن مجلدا يسمى swa-db-connections يحتفظ بملف staticwebapp.database.config.json .

ملاحظة

في مرحلة التطوير، إذا كنت تستخدم سلسلة اتصال للمصادقة، استخدم الدالة env() لقراءة سلسلة اتصال من متغير البيئة. يجب أن تكون السلسلة المرسلة إلى الدالة env محاطة بعلامات اقتباس.

أمان يستند إلى الدور

عند تعريف كيان في ملف staticwebapp.database.config.json ، يمكنك تحديد قائمة بالأدوار المطلوبة للوصول إلى نقطة نهاية الكيان.

يتطلب الجزء التالي من التكوين أن يصل دور المسؤول إلى جميع الإجراءات (create, read, update, delete) على كيان الأوامر .

{
...
"entities": { 
  "Orders": { 
    "source": "dbo.Orders", 
    "permissions": [ 
      { 
        "actions": ["*"], 
        "role": "admin" 
      }
    ]
 }
}
...
}

عندما تقوم بإجراء استدعاءات إلى نقطة نهاية تتطلب دورا، تكون الشروط التالية مطلوبة:

1. يجب أن يكون المستخدم الحالي مصادقة هويته.

2. يجب أن يكون المستخدم الحالي عضوا في الدور المطلوب.

3. يجب أن يتضمن طلب REST أو GraphQL رأسا يحتوي على مفتاح وقيمة X-MS-API-ROLE اسم الدور تطابق ما هو مدرج في قواعد تكوين الكيان.

   على سبيل المثال، يوضح المقطع التالي كيفية تمرير دور المسؤول في رأس طلب.

   {
     method: "POST",
     headers: { 
       "Content-Type": "application/json",
       "X-MS-API-ROLE": "admin"
     },
     body: JSON.stringify(requestPayload)
   }
   

القيود

• يجب أن تكون قواعد البيانات متاحة عبر بنية Azure التحتية.
• خلال المعاينة العامة، تتوسع الاتصالات من 0 إلى 1 عامل قاعدة بيانات.

الخطوات التالية

قم بتكوين قاعدة بياناتك