تكوين اتصال قاعدة البيانات في Azure Static Web Apps (معاينة)

تعمل اتصالات قاعدة بيانات تطبيقات Azure Static Web مع قواعد بيانات Azure المختلفة.

أثناء توصيل قاعدة بيانات بتطبيق الويب الثابت، تحتاج إلى تكوين جدار حماية قاعدة البيانات لقبول الوصول إلى الشبكة من العاملين في Static Web Apps من خلال السماح بالوصول إلى الشبكة من موارد Azure. لا يتم دعم السماح بعناوين IP محددة لتطبيقات الويب الثابتة.

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

استخدم هذا الجدول للحصول على تفاصيل حول جدار الحماية وتكوين الهوية المدارة لقاعدة البيانات الخاصة بك.

الاسم	نوع	جدار حمايه	الهوية المُدارة
Azure Cosmos DB	قياسي	تكوين جدار الحماية	تكوين الهوية المدارة
عنوان SQL لـ Azure	قياسي	تكوين جدار الحماية	تكوين الهوية المدارة
قاعدة بيانات Azure ل MySQL	فليكس	تكوين جدار الحماية	غير مدعوم
قاعدة بيانات Azure ل PostgreSQL	فليكس	تكوين جدار الحماية	غير مدعوم
قاعدة بيانات Azure ل PostgreSQL (مفرد)	فردي	تكوين جدار الحماية	تكوين الهوية المدارة

التكوين

يمكنك تعريف سلوك وقت التشغيل لاتصال قاعدة البيانات في staticwebapp.database.config.json الملف. قبل ربط قاعدة بيانات بتطبيق الويب الثابت، تحتاج إلى إنشاء هذا الملف داخل المستودع الخاص بك. حسب الاصطلاح، هذا الملف موجود في مجلد swa-db-connections في جذر المستودع الخاص بك، ولكن يمكنك نقله إذا كنت ترغب في ذلك.

الغرض من ملف التكوين هو:

• تعيين المسارات خارج /data-api نقطة النهاية إلى جداول قاعدة البيانات أو الكيانات
• كشف نقاط نهاية REST أو GraphQL (أو كليهما)
• تعريف قواعد أمان الكيان
• التحكم في إعدادات تكوين التطوير

إذا كنت تستخدم Azure Cosmos DB مع GraphQL، فستحتاج أيضا إلى توفير gql ملف مخطط.

إشعار

تتطلب اتصالات قاعدة بيانات Static Web Apps مجلدا يحتوي على ملفات التكوين. يجب أن يحتوي هذا المجلد على ملف التكوين staticwebapp.database.config.json لكافة أنواع قواعد البيانات. بالنسبة إلى Cosmos DB لقواعد بيانات NoSQL، مطلوب أيضا ملف مخطط staticwebapp.database.schema.gql .

حسب الاصطلاح، يسمى هذا المجلد swa-db-connections ويتم وضعه في جذر المستودع. يمكن تجاوز هذا الاصطلاح بمجلد تكوين مخصص.

عينة ملف تكوين

يوضح لك نموذج ملف التكوين التالي كيفية الاتصال بقاعدة بيانات Azure SQL وعرض كل من نقاط نهاية REST وGraphQL. للحصول على تفاصيل كاملة حول ملف التكوين وميزاته المدعومة، راجع وثائق Data API Builder.

{
  "$schema": "https://github.com/Azure/data-api-builder/releases/latest/download/dab.draft.schema.json",
  "data-source": {
    "database-type": "mssql",
    "options": {
      "set-session-context": false 
    },
    "connection-string": "@env('DATABASE_CONNECTION_STRING')"
  },
  "runtime": {
    "rest": {
      "enabled": true,
      "path": "/rest"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "host": {
      "mode": "production",
      "cors": {
        "origins": ["http://localhost:4280"],
        "allow-credentials": false
      },
      "authentication": {
        "provider": "StaticWebApps"
      }
    }
  },
  "entities": {
    "Person": {
      "source": "dbo.MyTestPersonTable",
      "permissions": [
        {
          "actions": ["create", "read", "update", "delete"],
          "role": "anonymous"
        }
      ]
    }
  }
}

الخاصية	‏‏الوصف
$schema	إصدار منشئ واجهة برمجة تطبيقات قاعدة البيانات المستخدمة من قبل Azure Static Web Apps لتفسير ملف التكوين.
data-source	إعدادات التكوين الخاصة بقاعدة البيانات الهدف. database-type تقبل الخاصية mssqlأو postgresqlcosmosdb_nosqlmysql. تتم الكتابة فوق سلسلة الاتصال عند النشر عند توصيل قاعدة بيانات بمورد Static Web Apps. أثناء التطوير المحلي، سلسلة الاتصال المعرفة في ملف التكوين هو ما يتم استخدامه للاتصال بقاعدة البيانات.
runtime	المقطع الذي يحدد نقاط النهاية المكشوفة. rest تتحكم الخاصيتان و graphql في جزء URL المستخدم للوصول إلى بروتوكول واجهة برمجة التطبيقات المعني. host يحدد قسم التكوين الإعدادات الخاصة ببيئة التطوير الخاصة بك. تأكد من أن origins الصفيف يتضمن عنوان المضيف المحلي والمنفذ. تتم الكتابة فوق host.mode عند production توصيل قاعدة بيانات بمورد Static Web Apps.
entities	القسم الذي يعين مسار URL إلى كيانات وجداول قاعدة البيانات. كما أن نفس قواعد المصادقة المستندة إلى الدور المستخدمة لتأمين المسارات تؤمن أيضا كيانات قاعدة البيانات ويمكن استخدامها لتحديد الأذونات لكل كيان. يحدد كائن الكيانات أيضا العلاقات بين الكيانات.

إنشاء ملف تكوين

يسمح لك Static Web Apps CLI بإنشاء كعب ملف تكوين.

هام

لتحسين أمان عمليات النشر من Static Web Apps CLI، تم إدخال تغيير فاصل يتطلب منك الترقية إلى أحدث إصدار (2.0.2) من Static Web Apps CLI بحلول 15 يناير 2025.

swa db init --database-type <YOUR_DATABASE_TYPE> استخدم لإنشاء ملف تكوين. بشكل افتراضي، ينشئ CLI staticwebapp.database.config.json جديدة في مجلد يسمى swa-db-connections.

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

• mssql
• postgresql
• cosmosdb_nosql
• mysql

مجلد التكوين المخصص

اسم المجلد الافتراضي لملف staticwebapp.database.config.json هو swa-db-connections. إذا كنت ترغب في استخدام مجلد مختلف، فستحتاج إلى تحديث ملف سير العمل لإخبار وقت تشغيل تطبيقات الويب الثابتة بمكان العثور على ملف التكوين الخاص بك. data_api_location تسمح لك الخاصية بتعريف موقع مجلد التكوين الخاص بك.

إشعار

يجب أن يكون المجلد الذي يحتوي على ملف staticwebapp.database.config.json في جذر مستودع تطبيقات الويب الثابتة.

توضح لك التعليمات البرمجية التالية كيفية استخدام مجلد يسمى db-config لملف تكوين قاعدة البيانات.

app_location: "/src"
api_location: "api"
output_location: "/dist"
data_api_location: "db-config" # Folder holding the staticwebapp.database.config.json file

تكوين اتصال قاعدة البيانات

يجب أن يكون لدى Azure Static Web Apps حق الوصول إلى الشبكة إلى قاعدة البيانات الخاصة بك حتى تعمل اتصالات قاعدة البيانات. بالإضافة إلى ذلك، لاستخدام قاعدة بيانات Azure للتطوير المحلي، تحتاج إلى تكوين قاعدة البيانات الخاصة بك للسماح بالطلبات من عنوان IP الخاص بك. فيما يلي خطوات عامة تنطبق على جميع قواعد البيانات. للحصول على خطوات محددة لنوع قاعدة البيانات، راجع الارتباطات أعلاه.

• انتقل إلى قاعدة البيانات في مدخل Microsoft Azure.
• انتقل إلى علامة التبويب Networking.
• ضمن قسم Firewall rules، حدد Add your client IPv4 address. تضمن هذه الخطوة أنه يمكنك استخدام قاعدة البيانات هذه للتطوير المحلي.
• حدد خانة الاختيار السماح لخدمات وموارد Azure بالوصول إلى هذا الخادم . تضمن هذه الخطوة أن مورد Static Web Apps المنشور يمكنه الوصول إلى قاعدة البيانات الخاصة بك.
• حدد حفظ.

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

يؤدي ربط قاعدة بيانات بتطبيق الويب الثابت إلى إنشاء اتصال الإنتاج بين موقع الويب وقاعدة البيانات عند نشرها إلى Azure.

1. افتح تطبيق الويب الثابت في مدخل Microsoft Azure.

2. في قسم الإعدادات ، حدد اتصال قاعدة البيانات.

3. ضمن قسم Production ، حدد رابط Link existing database .

4. في نافذة ربط قاعدة البيانات الموجودة، أدخل القيم التالية:

   الخاصية	القيمة
   نوع قاعدة البيانات	حدد نوع قاعدة البيانات من القائمة المنسدلة.
   الاشتراك	حدد اشتراك Azure من القائمة المنسدلة.
   اسم المورد	حدد اسم خادم قاعدة البيانات الذي يحتوي على قاعدة البيانات المطلوبة.
   اسم قاعدة البيانات	حدد اسم قاعدة البيانات التي تريد ربطها بتطبيق الويب الثابت.
   نوع المصادقة	حدد نوع الاتصال المطلوب للاتصال بقاعدة البيانات الخاصة بك.

المحتوى ذو الصلة

أضف قاعدة بيانات إلى تطبيق الويب الثابت باستخدام إحدى قواعد البيانات التالية:

• Azure Cosmos DB
• عنوان SQL لـ Azure
• MySQL
• PostgreSQL

بالإضافة إلى ذلك، يمكنك التعرف على كيفية استخدام منشئ واجهة برمجة تطبيقات البيانات مع Azure Static Web Apps.