استخدام OData للاستعلام عن البيانات

15 دقائق

OData هو بروتوكول للاستعلام عن واجهات برمجة تطبيقات RESTful. يستكشف هذا الدرس عدة طرق لتنفيذ عمليات CRUD مقابل Microsoft Dataverse البيانات.

إنشاء صف

لإنشاء صفوف، استخدم طريقة HTTP POST.

POST [Organization URI]/api/data/v9.2/accounts HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "Sample Account",
    "creditonhold": false,
    "address1_latitude": 47.639583,
    "description": "This is the description of the sample account",
    "revenue": 5000000,
    "accountcategorycode": 1
}

استرداد الصفوف

لاسترداد الصفوف، استخدم أسلوب HTTP GET.

يسترد النموذج التالي حسابًا بالمعرف 00000000-0000-0000-0000-000000000001:

GET [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)

تتوفر طرق أخرى للاستعلام عن البيانات باستخدام بناء جملة استعلام OData القياسي. لمزيد من المعلومات حول هذه العملية، راجع استرداد صف جدول باستخدام Web API.

تحديث الصفوف

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

إذا كنت تقوم بإجراء تحديث لقيم سمات متعددة، فاستخدم طريقة HTTP PATCH. حيث توفر طرق PATCH إمكانية upert إذا قمت بتوفير قيمة معرف كجزء من طلبك، وهي ميزة مفيدة عندما تقوم بمزامنة البيانات بين الأنظمة.
إذا كنت تقوم بتحديث قيمة سمة واحدة، فاستخدم الأسلوب HTTP PUT. لا يمكنك استخدام هذه الطريقة مع خصائص التنقل مثل عمليات البحث لأن ذلك يتطلب إزالة مرجع أيضًا.

يقوم المثال التالي بتحديث صف جدول الحساب:

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "name": "Updated Sample Account ",
    "creditonhold": true,
    "address1_latitude": 47.639583,
    "description": "This is the updated description of the sample account",
    "revenue": 6000000,
    "accountcategorycode": 2
}

إذا كنت تريد استرداد البيانات من الجدول الذي تقوم بتحديثه، فيمكنك استخدام رأس طلب return=representation. يمكنك إضافة استعلام $select إلى PATCH URL، إذا كنت تريد التحكم فِي الخصائص التي يتم إرجاعها. في المثال التالي، تمت إضافة الرأس و$select تم تعديله ليشمل سمات name وcreditonhold وaddress1 فقط.

طلب

PATCH [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)?$select=name,creditonhold,address1_latitude,description,revenue,accountcategorycode,createdon HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8
Prefer: return=representation

{"name":"Updated Sample Account"}

استجابة

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
Preference-Applied: return=representation
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#accounts/$entity",
    "@odata.etag": "W/"536537"",
    "accountid": "00000000-0000-0000-0000-000000000001",
    "accountcategorycode": 1,
    "description": "This is the description of the sample account",
    "address1_latitude": 47.63958,
    "creditonhold": false,
    "name": "Updated Sample Account",
    "createdon": "2023-09-28T23:14:00Z",
    "revenue": 5000000.0000,
    "_transactioncurrencyid_value": "048dddaa-6f7f-e611-80d3-00155db5e0b6"
}

التعليمة البرمجية التالية هي نموذج لطلب PUT حيث يتم تحديث اسم الحساب لصف معين:

PUT [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001)/name HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{"value": "Updated Sample Account Name"}

حذف الصفوف

لحذف الصفوف، استخدم أسلوب HTTP DELETE. العملية واضحة ومباشرة، حيث تقوم بتوفير URI لصف الجدول الذي تريد حذفه، كما موضح فِي الطلب التالي:

DELETE [Organization URI]/api/data/v9.2/accounts(00000000-0000-0000-0000-000000000001) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

الملاحظات

هل كانت هذه الصفحة مفيدة؟