بدء استخدام ميزات JSON في قاعدة بيانات Azure SQL ومثيل Azure SQL المُدار

ينطبق على: قاعدة بيانات Azure SQL مثيل Azure SQL المُدار

تتيح لك قاعدة بيانات Azure SQL ومثيل Azure SQL المُدار تحليل البيانات والاستعلام عنها في تنسيق (JSON)، وتصدير البيانات العلائقية كنص JSON. تُتاح سيناريوهات JSON التالية على النحو التالي:

• تنسيق البيانات العلائقية بتنسيق JSON باستخدام عبارة FOR JSON.
• العمل مع بيانات JSON
• الاستعلام عن بيانات JSON باستخدام الدوال العددية JSON.
• تحويل JSON إلى تنسيق جدولي باستخدام الدالة OPENJSON.

تنسيق البيانات العلائقية بتنسيق JSON

إذا كانت لديك خدمة ويب تأخذ البيانات من طبقة قاعدة البيانات وتوفر استجابة بتنسيق JSON أو أطر عمل JavaScript من جانب العميل أو مكتبات تقبل البيانات المنسقة بتنسيق JSON، يمكنك تنسيق محتوى قاعدة البيانات كملف JSON مباشرة في استعلام SQL. لم تعد مضطراً إلى كتابة تعليمات برمجية للتطبيق تعمل على تنسيق النتائج من قاعدة بيانات Azure SQL أو مثيل Azure SQL المُدار مثل JSON، أو تضمين بعض مكتبة التسلسل JSON لتحويل نتائج الاستعلام المجدولة ثم تسلسل الكائنات إلى تنسيق JSON. وبدلاً من ذلك، يمكنك استخدام عبارة FOR JSON لتنسيق نتائج استعلام SQL كـ JSON واستخدامها مباشرةً في تطبيقك.

في المثال التالي، تم تنسيق الصفوف من الجدول Sales.Customer بتنسيق JSON باستخدام عبارة FOR JSON:

select CustomerName, PhoneNumber, FaxNumber
from Sales.Customers
FOR JSON PATH

تقوم عبارة FOR JSON PATH بتنسيق نتائج الاستعلام كنص JSON. تُستخدم أسماء الأعمدة كمفاتيح، بينما يتم إنشاء قيم الخلايا كقيم JSON:

[
{"CustomerName":"Eric Torres","PhoneNumber":"(307) 555-0100","FaxNumber":"(307) 555-0101"},
{"CustomerName":"Cosmina Vlad","PhoneNumber":"(505) 555-0100","FaxNumber":"(505) 555-0101"},
{"CustomerName":"Bala Dixit","PhoneNumber":"(209) 555-0100","FaxNumber":"(209) 555-0101"}
]

يتم تنسيق مجموعة النتائج كمصفوفة JSON حيث يتم تنسيق كل صف ككائن JSON منفصل.

يشير PATH إلى أنه يمكنك تخصيص تنسيق الإخراج لنتيجة JSON باستخدام تدوين النقطة في الأسماء المستعارة للأعمدة. يغير الاستعلام التالي اسم مفتاح "CustomerName" في تنسيق JSON الناتج، ويضع أرقام الهاتف والفاكس في العنصر الفرعي "Contact":

select CustomerName as Name, PhoneNumber as [Contact.Phone], FaxNumber as [Contact.Fax]
from Sales.Customers
where CustomerID = 931
FOR JSON PATH, WITHOUT_ARRAY_WRAPPER

يبدو ناتج هذا الاستعلام كما يلي:

{
    "Name":"Nada Jovanovic",
    "Contact":{
           "Phone":"(215) 555-0100",
           "Fax":"(215) 555-0101"
    }
}

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

القيمة الرئيسية لعبارة FOR JSON هي أنها تسمح لك بإرجاع البيانات الهرمية المعقدة من قاعدة البيانات لديك المنسقة باعتبارها عناصر أو مصفوفات JSON متداخلة. يوضح المثال التالي كيفية تضمين الصفوف من الجدول Orders التي تنتمي إلى Customer كمصفوفة متداخلة من Orders:

select CustomerName as Name, PhoneNumber as Phone, FaxNumber as Fax,
        Orders.OrderID, Orders.OrderDate, Orders.ExpectedDeliveryDate
from Sales.Customers Customer
    join Sales.Orders Orders
        on Customer.CustomerID = Orders.CustomerID
where Customer.CustomerID = 931
FOR JSON AUTO, WITHOUT_ARRAY_WRAPPER

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

{
  "Name":"Nada Jovanovic",
  "Phone":"(215) 555-0100",
  "Fax":"(215) 555-0101",
  "Orders":[
    {"OrderID":382,"OrderDate":"2013-01-07","ExpectedDeliveryDate":"2013-01-08"},
    {"OrderID":395,"OrderDate":"2013-01-07","ExpectedDeliveryDate":"2013-01-08"},
    {"OrderID":1657,"OrderDate":"2013-01-31","ExpectedDeliveryDate":"2013-02-01"}
  ]
}

العمل مع بيانات JSON

إذا لم يكن لديك بيانات منظمة تنظيماً تاماً، أو إذا كان لديك عناصر فرعية معقدة، أو صفائف، أو بيانات هرمية، أو إذا كانت هياكل البيانات لديك تتطور بمرور الوقت، فيمكن أن يساعدك تنسيق JSON في تمثيل أي بنية بيانات معقدة.

JSON هو عبارة عن تنسيق نصي يمكن استخدامه مثل أي نوع سلسلة آخر في قاعدة بيانات Azure SQL ومثيل Azure SQL المُدار. يمكنك إرسال بيانات JSON أو تخزينها على هيئة NVARCHAR قياسي:

CREATE TABLE Products (
  Id int identity primary key,
  Title nvarchar(200),
  Data nvarchar(max)
)
go
CREATE PROCEDURE InsertProduct(@title nvarchar(200), @json nvarchar(max))
AS BEGIN
    insert into Products(Title, Data)
    values(@title, @json)
END

يتم تمثيل بيانات JSON المستخدمة في هذا المثال باستخدام نوع NVARCHAR (MAX). يمكن إدراج JSON في هذا الجدول أو توفيره كوسيطة للإجراء المخزن باستخدام صيغة Transact-SQL القياسية كما هو موضح في المثال التالي:

EXEC InsertProduct 'Toy car', '{"Price":50,"Color":"White","tags":["toy","children","games"]}'

كما أن أي لغة أو مكتبة من جانب العميل تعمل مع بيانات السلسلة في قاعدة بيانات Azure SQL ومثيل Azure SQL المُدار ستعمل مع بيانات JSON. يمكن تخزين JSON في أي جدول يدعم نوع NVARCHAR، مثل الجدول المحسن للذاكرة أو جدول بإصدارات النظام. لا يقدم JSON أي قيد سواء في التعليمات البرمجية من جانب العميل أو في طبقة قاعدة البيانات.

الاستعلام عن بيانات JSON

إذا كانت لديك بيانات منسقة بتنسيق JSON مخزنة في جداول Azure SQL، فإن دوال JSON تتيح لك استخدام هذه البيانات في أي استعلام SQL.

تتيح لك دوال JSON المتوفرة في قاعدة بيانات Azure SQL ومثيل Azure SQL المُدار معالجة البيانات المنسقة على هيئة JSON مثل أي نوع بيانات SQL آخر. يمكنك بسهولة استخراج القيم من نص JSON، واستخدام بيانات JSON في أي استعلام:

select Id, Title, JSON_VALUE(Data, '$.Color'), JSON_QUERY(Data, '$.tags')
from Products
where JSON_VALUE(Data, '$.Color') = 'White'

update Products
set Data = JSON_MODIFY(Data, '$.Price', 60)
where Id = 1

تستخرج الدالة JSON_VALUE قيمة من نص JSON المخزن في عمود البيانات. تستخدم هذه الدالة مساراً يشبه JavaScript للإشارة إلى قيمة في نص JSON لاستخراجها. يمكن استخدام القيمة المستخرجة في أي جزء من استعلام SQL.

الدالة JSON_QUERY مشابهة لـ JSON_VALUE. بخلاف JSON_VALUE، تستخرج هذه الدالة عنصراً فرعياً معقداً مثل المصفوفات أو العناصر الموضوعة في نص JSON.

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

نظراً لأنه يتم تخزين JSON في نص قياسي، فلا توجد ضمانات على تنسيق القيم المخزنة في أعمدة النص بشكل صحيح. يمكنك التحقق من تنسيق النص المخزن في عمود JSON بشكل صحيح باستخدام قيود التحقق من قاعدة بيانات Azure SQL القياسية ودالة ISJSON:

ALTER TABLE Products
    ADD CONSTRAINT [Data should be formatted as JSON]
        CHECK (ISJSON(Data) > 0)

إذا تم تنسيق نص الإدخال بشكل صحيح JSON، فإن الدالة ISJSON ترجع القيمة 1. في كل إدخال أو تحديث لعمود JSON، سيتحقق هذا القيد من أن القيمة النصية الجديدة ليست بتنسيق JSON غير صحيح.

تحويل JSON إلى تنسيق جدولي

كما تتيح لك قاعدة بيانات Azure SQL ومثيل Azure SQL المُدار أيضاً تحويل مجموعات JSON إلى تنسيق جدولي وتحميل بيانات JSON أو الاستعلام عنها.

OPENJSON هي دالة ذات قيمة جدولية والتي تحلل نص JSON، وتحدد موقع مصفوفة من عناصر JSON، وتكرر خلال عناصر المصفوفة، وتُرجع صفاً واحداً في نتيجة الإخراج لكل عنصر من عناصر المصفوفة.

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

يمكننا تحويل مصفوفة JSON في المتغير @orders إلى مجموعة من الصفوف، أو تحليل مجموعة النتائج هذه، أو إدراج صفوف في جدول قياسي:

CREATE PROCEDURE InsertOrders(@orders nvarchar(max))
AS BEGIN

    insert into Orders(Number, Date, Customer, Quantity)
    select Number, Date, Customer, Quantity
    FROM OPENJSON (@orders)
     WITH (
            Number varchar(200),
            Date datetime,
            Customer varchar(200),
            Quantity int
     )
END

يمكن تحليل مجموعة الأوامر المنسقة كمصفوفة JSON والمتوفرة كمعامل للإجراء المخزن وإدراجها في جدول الطلبات.