نسخ البيانات وتحويلها من نقطة نهاية REST وإليها باستخدامAzure Data Factory

مقالة
02/26/2024

ينطبق على:Azure Data Factory Azure Synapse Analytics

تلميح

جرب Data Factory في Microsoft Fabric، وهو حل تحليلي متكامل للمؤسسات. يغطي Microsoft Fabric كل شيء بدءا من حركة البيانات إلى علم البيانات والتحليلات في الوقت الحقيقي والمعلومات المهنية وإعداد التقارير. تعرف على كيفية بدء إصدار تجريبي جديد مجانا!

توضح هذه المقالة كيفية استخدام Copy Activity في Azure Data Factory لنسخ البيانات من نقطة نهاية REST وإليها. يعتمد المقال على Copy Activity في Azure Data Factory، الذي يقدم نظرة عامة على Copy Activity.

الفرق بين موصل REST هذا، موصل HTTP،وموصل جدول ويب هو:

يدعم موصل REST بشكل خاص نسخ البيانات من واجهات برمجة التطبيقات RESTful.
موصل HTTP عام لاسترداد البيانات من أي نقطة نهاية HTTP، على سبيل المثال، لتنزيل الملف. قبل استخدام موصل REST هذا، قد يحدث استخدام موصل HTTP لنسخ البيانات من واجهات برمجة التطبيقات (API) RESTful، التي يتم دعمها ولكنها أقل فعالية مقارنة بموصل REST.
موصل جدول ويب يستخرج محتوى جدول من صفحة ويب HTML.

القدرات المدعومة

موصل Azure Files هذا مدعوم للإمكانيات التالية:

القدرات المدعومة	IR
Copy activity (المصدر/المتلق)	(1) (2)
تعيين تدفق البيانات (المصدر/ المتلقي)	(1)

① وقت تشغيل تكامل Azure ② وقت تشغيل التكامل المستضاف ذاتيًا

للحصول على قائمة مخازن البيانات المعتمدة كمصادر ومواضع تلقي، راجع مخازن البيانات المعتمدة.

وعلى وجه التحديد، يدعم موصل REST العام هذا:

نسخ البيانات من نقطة نهاية REST باستخدام الأساليب GET أو POST ونسخ البيانات إلى نقطة نهاية REST باستخدام الأساليب POST أو PUT أو PATCH.
نسخ البيانات باستخدام إحدى المصادقات التالية: المجهولة والأساسية وكيان الخدمة وبيانات اعتماد عميل OAuth2 والهوية المُدارة التي يُعينها النظام والهوية المُدارة التي يُعينها المستخدم.
ترقيم الصفحات في واجهات برمجة التطبيقات REST.
بالنسبة ل REST كمصدر، يتم نسخ استجابة REST JSON كما هي أو تحليلها باستخدام تعيين المخطط. يتم دعم حمولة الاستجابة فقط في JSON.

تلميح

لاختبار طلب إسترداد البيانات قبل تكوين موصل REST في Data Factory، تعرف على مواصفات API لمتطلبات الرأس والنص. يمكنك استخدام أدوات مثل Postman أو مستعرض ويب للتحقق من صحة.

المتطلبات الأساسية

إذا كان مخزن البيانات الخاص بك موجوداً داخل شبكة محلية، أو شبكة Azure ظاهرية، أو Amazon Virtual Private Cloud، فأنت بحاجة إلى تكوين وقت تشغيل تكامل مستضاف ذاتياً للاتصال به.

إذا كان مخزن البيانات الخاص بك عبارة عن خدمة بيانات سحابية مُدارة، يمكنك استخدام Azure Integration Runtime. إذا كان الوصول مقتصراً على عناوين IP التي تمت الموافقة عليها في قواعد جدار الحماية، يمكنك إضافة عناوين IP لـ Azure Integration Runtime إلى قائمة السماح.

يمكنك أيضاً استخدام ميزة وقت تشغيل تكامل الشبكة الظاهرية المُدارة في Azure Data Factory للوصول إلى الشبكة المحلية دون تثبيت وقت تشغيل تكامل مستضاف ذاتياً وتكوينه.

لمزيد من المعلومات حول آليات وخيارات أمان الشبكة التي يدعمها Data Factory، راجع إستراتيجيات الوصول إلى البيانات.

الشروع في العمل

لتنفيذ نشاط النسخ باستخدام أحد المسارات، يمكنك استخدام إحدى الأدوات أو عدد تطوير البرامج التالية:

قم بإنشاء خدمة REST المرتبطة باستخدام واجهة المستخدم

استخدم الخطوات التالية لإنشاء خدمة REST المرتبطة في واجهة مستخدم مدخل Azure.

استعرض للوصول إلى علامة تبويب "Manage" في Azure Data Factory أو مساحة عمل Synapse وحدد "Linked Services"، ثم حدد "New":
- Azure Data Factory
- Azure Synapse
ابحث عن REST وحدد موصل REST.
قم بتكوين تفاصيل الخدمة، واختبر الاتصال، وأنشئ الخدمة المرتبطة الجديدة.

تفاصيل تكوين الموصل

توفر الأقسام التالية تفاصيل حول الخصائص التي يمكنك استخدامها لتحديد كيانات مصنع البيانات الخاصة بموصل REST.

خصائص الخدمة المرتبطة

الخصائص التالية مدعومة لخدمة REST المرتبطة:

الخاصية	الوصف	مطلوب
النوع	يجب تعيين خاصية النوع إلى RestService.	‏‏نعم‬
عنوان URL	عنوان URL الأساسي لخدمة REST.	‏‏نعم‬
enableServerCertificateValidation	التحقق من صحة شهادة TLS/SSL على جانب الخادم عند الاتصال بنقطة النهاية.	لا (القيمة الافتراضية هي true)
نوع المصادقة	نوع المصادقة المستخدمة للاتصال بخدمة REST. القيم المسموح بها هي Anonymous وBasic وAadServicePrincipal وOAuth2ClientCredential وManagedServiceIdentity. يمكنك أيضاً تكوين رءوس المصادقة في الخاصية `authHeaders`. راجع الأقسام المقابلة أدناه حول المزيد من الخصائص والأمثلة على التوالي.	‏‏نعم‬
authHeaders	رؤوس طلب HTTP إضافية للمصادقة. على سبيل المثال، لاستخدام مصادقة مفتاح API، يمكنك تحديد نوع المصادقة ك "Anonymous" وتحديد مفتاح API في العنوان.	لا
connectVia	وقت تشغيل التكامل المطلوب استخدامه للاتصال بمخزن البيانات. تعرف على المزيد من قسم المتطلبات الأساسية. في حالة عدم التحديد، تستخدم هذه الخاصية وقت تشغيل تكامل Azure الافتراضي.	لا

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

المصادقة الأساسية
المصادقة باستخدام الخدمة الرئيسية
مصادقة بيانات اعتماد عميل OAuth2
مصادقة الهوية المدارة المعينة من قبل النظام
مصادقة الهوية المدارة المعينة من قبل المستخدم
مصادقة مجهولة

قم باستخدام المصادقة الأساسية

تعيين خاصية authenticationType إلى Basic. بالإضافة إلى الخصائص العامة الموصوفة في القسم السابق، حدد الخصائص التالية:

الخاصية	الوصف	مطلوب
userName	اسم المستخدم لاستخدام الوصول إلى نقطة النهاية REST.	‏‏نعم‬
كلمة المرور	كلمة المرور للمستخدم (قيمة userName). قم بوضع علامة على هذا الحقل كنوع SecureString لتخزينه بشكل آمن في Data Factory. يمكنك أيضاً الإشارة إلى سر مخزن في Azure Key Vault.	‏‏نعم‬

مثال

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "authenticationType": "Basic",
            "url" : "<REST endpoint>",
            "userName": "<user name>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

استخدام المصادقة الرئيسية للخدمة

قم بتعيين خاصية authenticationType إلى AadServicePrincipal. بالإضافة إلى الخصائص العامة الموصوفة في القسم السابق، حدد الخصائص التالية:

الخاصية	الوصف	مطلوب
servicePrincipalId	حدد معرف عميل تطبيق Microsoft Entra.	‏‏نعم‬
servicePrincipalKey	حدد مفتاح تطبيق Microsoft Entra. قم بوضع علامة على هذا الحقل ك SecureString لتخزينه بشكل آمن في Data Factory أو الإشارة إلى سر مخزن في Azure Key Vault.	‏‏نعم‬
tenant	حدد معلومات المستأجر (اسم المجال أو معرف المستأجر) التي يوجد داخلها التطبيق. يمكنك إستردادها عن طريق تحريك الماوس في الركن العلوي الأيمن من بوابة Azure.	‏‏نعم‬
aadResourceId	حدد مورد Microsoft Entra الذي تطلبه للتخويل، على سبيل المثال، `https://management.core.windows.net`.	‏‏نعم‬
azureCloudType	بالنسبة للمصادقة الأساسية للخدمة، حدد نوع بيئة سحابة Azure التي تم تسجيل تطبيق Microsoft Entra إليها. القيم المسموح بها هي AzurePublic، وAzureChina، وAzureUsGovernment، وAzureGermany. يتم استخدام بيئة سحابة data factory بشكل افتراضي.	لا

مثال

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalKey": {
                "value": "<service principal key>",
                "type": "SecureString"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

استخدام مصادقة بيانات اعتماد عميل OAuth2

عيّن الخاصية authenticationType إلى OAuth2ClientCredential. بالإضافة إلى الخصائص العامة الموصوفة في القسم السابق، حدد الخصائص التالية:

الخاصية	الوصف	مطلوب
tokenEndpoint	نقطة نهاية الرمز المميز لخادم التخويل للحصول على الرمز المميز للوصول.	‏‏نعم‬
clientId	معرّف العميل المرتبط بتطبيقك.	‏‏نعم‬
clientSecret	سر العميل المرتبط بتطبيقك. قم بوضع علامة على هذا الحقل كنوع SecureString لتخزينه بشكل آمن في Data Factory. يمكنك أيضاً الإشارة إلى سر مخزن في Azure Key Vault.	‏‏نعم‬
النطاق	نطاق الوصول المطلوب. يصف نوع الوصول الذي سيتم طلبه.	لا
resource	الخدمة أو المورد المستهدف الذي سيتم طلب الوصول إليه.	لا

مثال

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "enableServerCertificateValidation": true,
            "authenticationType": "OAuth2ClientCredential",
            "clientId": "<client ID>",
            "clientSecret": {
                "type": "SecureString",
                "value": "<client secret>"
            },
            "tokenEndpoint": "<token endpoint>",
            "scope": "<scope>",
            "resource": "<resource>"
        }
    }
}

استخدام مصادقة الهوية المدارة المعينة من قبل النظام

قم بتعيين خاصية authenticationType إلى ManagedServiceIdentity. بالإضافة إلى الخصائص العامة الموصوفة في القسم السابق، حدد الخصائص التالية:

الخاصية	الوصف	مطلوب
aadResourceId	حدد مورد Microsoft Entra الذي تطلبه للتخويل، على سبيل المثال، `https://management.core.windows.net`.	‏‏نعم‬

مثال

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<AAD resource URL e.g. https://management.core.windows.net>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

استخدام مصادقة الهوية المدارة المعينة من قبل المستخدم

الخاصية	الوصف	مطلوب
aadResourceId	حدد مورد Microsoft Entra الذي تطلبه للتخويل، على سبيل المثال، `https://management.core.windows.net`.	‏‏نعم‬
بيانات الاعتماد	حدد الهوية المدارة المعينة من قبل المستخدم ككائن بيانات الاعتماد.	‏‏نعم‬

مثال

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "ManagedServiceIdentity",
            "aadResourceId": "<Azure AD resource URL e.g. https://management.core.windows.net>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            }    
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

استخدام رءوس المصادقة

بالإضافة إلى ذلك، يمكنك تكوين رؤوس الطلبات للمصادقة مع أنواع المصادقة المضمنة.

مثال: استخدام مصادقة مفتاح API

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint>",
            "authenticationType": "Anonymous",
            "authHeaders": {
                "x-api-key": {
                    "type": "SecureString",
                    "value": "<API key>"
                }
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

خصائص مجموعة البيانات

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

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

لنسخ البيانات من REST، يتم اعتماد الخصائص التالية:

الخاصية	الوصف	مطلوب
النوع	يجب تعيين خاصية type لمجموعة البيانات إلى RestResource.	‏‏نعم‬
relativeUrl	عنوان "URL" نسبي للمورد الذي يحتوي على البيانات. في حالة عدم تحديد هذه الخاصية، يتم استخدام عنوان URL المحدد في تعريف الخدمة المرتبط فقط. ينسخ موصل HTTP البيانات من URL المجمع: `[URL specified in linked service]/[relative URL specified in dataset]`.	لا

إذا كنت تقوم بإعداد requestMethod وadditionalHeaders وrequestBody وpaginationRules في مجموعة البيانات، فإنه لا يزال مدعوماً كما هو، بينما يقترح عليك استخدام النموذج الجديد في النشاط قيد التقدم.

مثال:

{
    "name": "RESTDataset",
    "properties": {
        "type": "RestResource",
        "typeProperties": {
            "relativeUrl": "<relative url>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<REST linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

خصائص نشاط النسخ

يوفر هذا القسم قائمة بالخصائص التي يدعمها مصدر REST ومتلقي نظام الملفات.

للحصول على قائمة كاملة بالأقسام والخصائص المتوفرة لتعريف الأنشطة، راجع المسارات.

REST كمصدر

تُدعم الخصائص التالية في قسم مصدر نشاط النسخ:

الخاصية	الوصف	مطلوب
النوع	يجب تعيين الخاصية type الخاصة بمصدر copy activity إلى RestSource.	‏‏نعم‬
requestMethod	أسلوب HTTP. القيم المسموح بها هي true و(default) وPOST.	لا
additionalHeaders	رؤوس طلب HTTP إضافية.	لا
requestBody	النص الأساسي لطلب HTTP.	لا
paginationRules	قواعد ترقيم الصفحات لإنشاء طلبات الصفحة التالية. راجع قسم دعم ترقيم صفحات حول التفاصيل.	لا
httpRequestTimeout	المهلة (قيمة TimeSpan) لطلب HTTP للحصول على استجابة. هذه القيمة هي المهلة للحصول على استجابة، وليست المهلة لقراءة بيانات الاستجابة. القيمة الافتراضية هي 00:01:40.	لا
requestInterval	وقت الانتظار قبل إرسال طلب الصفحة التالية. القيمة الافتراضية هي 00:00:01	لا

إشعار

يتجاهل موصل REST أي رأس "Accept" محدد في additionalHeaders. نظراً لأن موصل REST يدعم الاستجابة في JSON فقط، فإنه سيقوم تلقائياً بإنشاء رأس Accept: application/json.
صفيف الكائن كنص الاستجابة غير معتمد في ترقيم الصفحات.

المثال 1: استخدام أسلوب Get مع تعيين ترقيم الصفحات

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "additionalHeaders": {
                    "x-user-defined": "helloworld"
                },
                "paginationRules": {
                    "AbsoluteUrl": "$.paging.next"
                },
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

مثال 2: استخدام أسلوب Post

"activities":[
    {
        "name": "CopyFromREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<REST input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "RestSource",
                "requestMethod": "Post",
                "requestBody": "<body for POST REST request>",
                "httpRequestTimeout": "00:01:00"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

REST كمتلقي

تُدعم الخصائص التالية في قسم متلقي نشاط النسخ:

الخاصية	الوصف	مطلوب
النوع	يجب تعيين خاصية type لمتلقي copy activity إلى RestSink.	‏‏نعم‬
requestMethod	أسلوب HTTP. القيم المسموح بها هي POST (default) وPUT وPATCH.	لا
additionalHeaders	رؤوس طلب HTTP إضافية.	لا
httpRequestTimeout	المهلة (قيمة TimeSpan) لطلب HTTP للحصول على استجابة. هذه القيمة هي المهلة للحصول على استجابة، وليست المهلة لكتابة البيانات. القيمة الافتراضية هي 00:01:40.	لا
requestInterval	وقت الفاصل بين الطلبات المختلفة بالمللي ثانية. يجب أن تكون قيمة الفاصل الزمني للطلب رقماً بين [10، 60000].	لا
httpCompressionType	نوع ضغط HTTP لاستخدامه أثناء إرسال بيانات ذات مستوى ضغط مثالي. القيم المسموح بها هي none و gzip.	لا
writeBatchSize	عدد السجلات التي يجب كتابتها إلى مصدر REST لكل دفعة. القيمة الافتراضية هي 10000.	لا

يعمل موصل REST كمتلقي مع باقي واجهات API التي تقبل JSON. سيتم إرسال البيانات في JSON مع النمط التالي. حسب الحاجة، يمكنك استخدام تعيين المخطط لـ copy activity لإعادة تشكيل البيانات المصدر لتتوافق مع الحمولة المتوقعة من قبل REST API.

[
    { <data object> },
    { <data object> },
    ...
]

مثال:

"activities":[
    {
        "name": "CopyToREST",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<REST output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "RestSink",
                "requestMethod": "POST",
                "httpRequestTimeout": "00:01:40",
                "requestInterval": 10,
                "writeBatchSize": 10000,
                "httpCompressionType": "none",
            },
        }
    }
]

تعيين خصائص تدفق البيانات

يتم دعم REST في تدفقات البيانات لكل من مجموعات بيانات التكامل ومجموعات البيانات المضمنة.

تحويل المصدر

الخاصية	الوصف	مطلوب
requestMethod	أسلوب HTTP. القيم المسموح بها هي GET و POST.	‏‏نعم‬
relativeUrl	عنوان "URL" نسبي للمورد الذي يحتوي على البيانات. في حالة عدم تحديد هذه الخاصية، يتم استخدام عنوان URL المحدد في تعريف الخدمة المرتبط فقط. ينسخ موصل HTTP البيانات من URL المجمع: `[URL specified in linked service]/[relative URL specified in dataset]`.	لا
additionalHeaders	رؤوس طلب HTTP إضافية.	لا
httpRequestTimeout	المهلة (قيمة TimeSpan) لطلب HTTP للحصول على استجابة. هذه القيمة هي المهلة للحصول على استجابة، وليست المهلة لكتابة البيانات. القيمة الافتراضية هي 00:01:40.	لا
requestInterval	وقت الفاصل بين الطلبات المختلفة بالمللي ثانية. يجب أن تكون قيمة الفاصل الزمني للطلب رقماً بين [10، 60000].	لا
QueryParameters.request_query_parameter أو QueryParameters['request_query_parameter']	"request_query_parameter" معرف من قبل المستخدم، يشير إلى اسم معلمة استعلام في URL لطلب HTTP التالي.	لا

تحويل المتلقي

الخاصية	الوصف	مطلوب
additionalHeaders	رؤوس طلب HTTP إضافية.	لا
httpRequestTimeout	المهلة (قيمة TimeSpan) لطلب HTTP للحصول على استجابة. هذه القيمة هي المهلة للحصول على استجابة، وليست المهلة لكتابة البيانات. القيمة الافتراضية هي 00:01:40.	لا
requestInterval	وقت الفاصل بين الطلبات المختلفة بالمللي ثانية. يجب أن تكون قيمة الفاصل الزمني للطلب رقماً بين [10، 60000].	لا
httpCompressionType	نوع ضغط HTTP لاستخدامه أثناء إرسال بيانات ذات مستوى ضغط مثالي. القيم المسموح بها هي none و gzip.	لا
writeBatchSize	عدد السجلات التي يجب كتابتها إلى مصدر REST لكل دفعة. القيمة الافتراضية هي 10000.	لا

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

Data flow REST sink

نموذج برنامج نصي لتدفق البيانات

لاحظ استخدام تبديل الصفوف قبل المتلقي لإرشاد ADF بنوع الإجراء الذي يتعين عليك اتخاذه مع باقي متلقي REST الخاص بك. أي إدراج أو تحديث أو إصدار أو حذف.

AlterRow1 sink(allowSchemaDrift: true,
	validateSchema: false,
	deletable:true,
	insertable:true,
	updateable:true,
	upsertable:true,
	rowRelativeUrl: 'periods',
	insertHttpMethod: 'PUT',
	deleteHttpMethod: 'DELETE',
	upsertHttpMethod: 'PUT',
	updateHttpMethod: 'PATCH',
	timeout: 30,
	requestFormat: ['type' -> 'json'],
	skipDuplicateMapInputs: true,
	skipDuplicateMapOutputs: true) ~> sink1

دعم ترقيم الصفحات

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

يدعم موصل REST العام هذا أنماط ترقيم الصفحات التالية:

URL المطلق أو النسبي للطلب التالي = قيمة الخاصية في نص الاستجابة الحالي
URL المطلق أو النسبي للطلب التالي = قيمة رأس في رءوس الاستجابة الحالية
معلمة استعلام الطلب التالي = قيمة الخاصية في نص الاستجابة الحالي
معلمة استعلام الطلب التالي = قيمة رأس في رءوس الاستجابة الحالية
عنوان الطلب التالي = قيمة الخاصية في نص الاستجابة الحالي
عنوان الطلب التالي = قيمة الرأس في رءوس الاستجابة الحالية

يتم تعريف قواعد ترقيم الصفحات كقاموس في مجموعة البيانات، التي تحتوي على زوج أو أكثر من أزواج قيم المفاتيح الحساسة لحالة الأحرف. سيتم استخدام التكوين لإنشاء الطلب بدءاً من الصفحة الثانية. سيتوقف الموصل عن التكرار عندما يحصل على رمز حالة HTTP 204 (No Content)، أو أي من تعبيرات JSONPath في "paginationRules" حيث ترجع قيمة خالية.

مفاتيح معتمدة في قواعد ترقيم الصفحات:

المفتاح	‏‏الوصف
AbsoluteUrl	يشير إلى عنوان URL لإصدار الطلب التالي. يمكن أن يكون إما URL المطلق أو URL النسبي.
QueryParameters.request_query_parameter أو QueryParameters['request_query_parameter']	"request_query_parameter" معرف من قبل المستخدم، يشير إلى اسم معلمة استعلام في URL لطلب HTTP التالي.
الرءوس.request_header أو الرءوس['request_header']	"request_header" معرف من قبل المستخدم، يشير إلى اسم رأس في طلب HTTP التالي.
EndCondition:end_condition	يتم تعريف «end_condition» من قِبل المستخدم، ما يشير إلى الحالة التي ستنهي حلقة فصل الصفحات في طلب HTTP التالي.
MaxRequestNumber	يشير إلى الحد الأقصى لرقم طلب فصل الصفحات. تركه فارغًا يعني عدم وجود حد.
SupportRFC5988	بشكل افتراضي، يتم تعيين هذا على صحيح إذا لم يتم تحديد قاعدة فصل الصفحات. يمكنك تعطيل هذه القاعدة عن طريق تعيين `supportRFC5988` على خطأ أو إزالة هذه الخاصية من البرنامج النصي.

القيم المعتمدة في قواعد ترقيم الصفحات:

قيمة	‏‏الوصف
الرءوس.Response_header أو الرءوس['response_header']	"response_header" معرف من قبل المستخدم، يشير إلى اسم رأس واحد في استجابة HTTP الحالية، سيتم استخدام قيمته لإصدار الطلب التالي.
تعبير JSONPath يبدأ ب "$" (يمثل جذر نص الاستجابة)	يجب أن يحتوي نص الاستجابة على كائن JSON واحد فقط ومصفوفة الكائن لأن نص الاستجابة غير مدعوم. يجب أن يرجع تعبير JSONPath قيمة بدائية واحدة سيتم استخدامها لإصدار الطلب التالي.

إشعار

تختلف قواعد فصل الصفحات في تعيين تدفقات البيانات عنها في نشاط النسخ في الجوانب التالية:

النطاق غير مدعوم في تعيين تدفقات البيانات.
[''] غير مدعوم في تعيين تدفقات البيانات. بدلاً من ذلك، استخدم {} للهروب من الحرف الخاص. على سبيل المثال، body.{@odata.nextLink}، الذي تحتوي عقدة JSON الخاصة به @odata.nextLink على حرف خاص ..
يتم دعم شرط النهاية في تعيين تدفقات البيانات، لكن بناء جملة الشرط يختلف عنه في نشاط النسخ. body يستخدم للإشارة إلى نص الاستجابة بدلاً من $. header يستخدم للإشارة إلى رأس الاستجابة بدلاً من headers. فيما يلي مثالان يوضحان هذا الاختلاف:
- المثال 1:
  نشاط النسخ: "EndCondition:$.data": "Empty"
  تعيين تدفقات البيانات: "EndCondition:body.data": "Empty"
- المثال 2:
  نشاط النسخ: "EndCondition:headers.complete": "Exist"
  تعيين تدفقات البيانات: "EndCondition:header.complete": "Exist"

أمثلة على قواعد فصل الصفحات

يوفر هذا القسم قائمة بأمثلة لإعدادات قواعد فصل الصفحات.

مثال 1: المتغيرات في QueryParameters

يوفر هذا المثال خطوات التكوين لإرسال طلبات متعددة توجد متغيراتها في QueryParameters.

طلبات متعددة:

baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0,
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
...... 
baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=10000

الخطوة 1: الإدخال sysparm_offset={offset} إما في عنوان URL الأساسي أو عنوان URL النسبي كما هو موضح في لقطات الشاشة التالية:

Screenshot showing one configuration to send multiple requests whose variables are in Query Parameters.

أو

Screenshot showing another configuration to send multiple requests whose variables are in Query Parameters.

الخطوة 2: تعيين قواعد فصل الصفحات إما كخيار 1 أو خيار 2:

الخيار 1: "QueryParameters.{offset}" : "RANGE:0:10000:1000"
الخيار 2: "AbsoluteUrl.{offset}" : "RANGE:0:10000:1000"

مثال 2: المتغيرات في AbsoluteUrl

يوفر هذا المثال خطوات التكوين لإرسال طلبات متعددة توجد متغيراتها في AbsoluteUrl.

طلبات متعددة:

BaseUrl/api/now/table/t1
BaseUrl/api/now/table/t2
...... 
BaseUrl/api/now/table/t100

الخطوة 1: إدخال {id} إما في عنوان URL الأساسي في صفحة تكوين الخدمة المرتبطة أو عنوان URL النسبي في جزء اتصال مجموعة البيانات.

Screenshot showing one configuration to send multiple requests whose variables are in Absolute Url.

أو

Screenshot showing another configuration to send multiple requests whose variables are in Absolute Url.

الخطوة 2: تعيين قواعد فصل الصفحات على أنها "AbsoluteUrl.{id}" :"RANGE:1:100:1".

مثال 3: المتغيرات في الرؤوس

يوفر هذا المثال خطوات التكوين لإرسال طلبات متعددة توجد متغيراتها في الرؤوس.

طلبات متعددة:
RequestUrl: https://example/table
الطلب 1: Header(id->0)
الطلب 2: Header(id->10)
......
الطلب 100: Header(id->100)

الخطوة 1: إدخال {id} في رؤوس إضافية.

الخطوة 2: تعيين قواعد فصل الصفحات على أنها "Headers.{id}" : "RARNGE:0:100:10".

Screenshot showing the pagination rule to send multiple requests whose variables are in Headers.

مثال 4: المتغيرات موجودة في AbsoluteUrl/QueryParameters/Headers، ولم يتم تحديد متغير النهاية مسبقًا وتعتمد حالة النهاية على الاستجابة

يوفر هذا المثال خطوات تكوين لإرسال طلبات متعددة توجد متغيراتها في AbsoluteUrl/QueryParameters/Headers ولكن لم يتم تحديد متغير النهاية. للاستجابات المختلفة، يتم عرض إعدادات مختلفة لقاعدة شرط النهاية في المثال 4.1-4.6.

طلبات متعددة:

Request 1: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=0, 
Request 2: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=1000,
Request 3: baseUrl/api/now/table/incident?sysparm_limit=1000&sysparm_offset=2000,
......

تمت مصادفة استجابتين في هذا المثال:

الاستجابة 1:

{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ]
}

الاستجابة 2:

{
    Data: [
        {key1: val5, key2: val6
        },
        {key1: val7, key2: val8
        }
    ]
}

الخطوة 1: تعيين نطاق قواعد فصل الصفحات كـ مثال 1 وترك نهاية النطاق فارغة كـ "AbsoluteUrl.{offset}": "RANGE:0:1000".

الخطوة 2: تعيين قواعد مختلفة لشرط النهاية وفقًا للاستجابات الأخيرة المختلفة. راجع الأمثلة أدناه:

المثال 4.1: ينتهي فصل الصفحات عندما تكون قيمة العقدة المحددة في الاستجابة فارغة

تُرجع واجهة برمجة تطبيقات REST الاستجابة الأخيرة بالهيكل التالي:
```
{
    Data: []
}
```
تعيين قاعدة شرط النهاية كـ "EndCondition:$.data": "Empty" لإنهاء فصل الصفحات عندما تكون قيمة العقدة المحددة في الاستجابة فارغة.
المثال 4.2: ينتهي ترقيم الصفحات عندما لا توجد قيمة العقدة المحددة استجابة للجرعة

تُرجع واجهة برمجة تطبيقات REST الاستجابة الأخيرة بالهيكل التالي:
```
{}
```
عيّن قاعدة شرط النهاية كـ "EndCondition:$.data": "NonExist" لإنهاء ترقيم الصفحات عندما لا تكون قيمة العقدة المحددة استجابةً لجرعة غير موجودة.
مثال 4.3: ينتهي فصل الصفحات عندما توجد قيمة العقدة المحددة في الاستجابة

تُرجع واجهة برمجة تطبيقات REST الاستجابة الأخيرة بالهيكل التالي:
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
تعيين قاعدة شرط النهاية كـ "EndCondition:$.Complete": "Exist" لإنهاء فصل الصفحات عندما توجد قيمة العقدة المحددة في الاستجابة.
مثال 4.4: ينتهي فصل الصفحات عندما تكون قيمة العقدة المحددة في الاستجابة قيمة ثابتة يحددها المستخدم

تُرجع واجهة برمجة تطبيقات REST الاستجابة بالهيكل التالي:
```
{
    Data: [
        {key1: val1, key2: val2
        },
        {key1: val3, key2: val4
        }
    ],
            Complete: false
}
```
......

وكانت الاستجابة الأخيرة في الهيكل التالي:
```
{
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}
```
تعيين قاعدة شرط النهاية كـ "EndCondition:$.Complete": "Const:true" لإنهاء فصل الصفحات عندما تكون قيمة العقدة المحددة في الاستجابة قيمة ثابتة يحددها المستخدم.
مثال 4.5: ينتهي فصل الصفحات عندما تكون قيمة مفتاح الرأس في الاستجابة تساوي قيمة ثابتة يحددها المستخدم

تظهر مفاتيح الرأس في استجابات واجهة برمجة تطبيقات REST في الهيكل أدناه:

رأس الاستجابة 1: header(Complete->0)
......
رأس الاستجابة الأخيرة: header(Complete->1)

تعيين قاعدة شرط النهاية كـ "EndCondition:headers.Complete": "Const:1" لإنهاء فصل الصفحات عندما تكون قيمة مفتاح الرأس في الاستجابة تساوي قيمة ثابت يحددها المستخدم.
مثال 4.6: ينتهي فصل الصفحات عند وجود المفتاح في رأس الاستجابة

تظهر مفاتيح الرأس في استجابات واجهة برمجة تطبيقات REST في الهيكل أدناه:

رأس الاستجابة 1: header()
......
رأس الاستجابة الأخيرة: header(CompleteTime->20220920)

تعيين قاعدة شرط النهاية كـ "EndCondition:headers.CompleteTime": "Exist" لإنهاء فصل الصفحات عندما يكون المفتاح موجودًا في رأس الاستجابة.

مثال 5: تعيين شرط النهاية لتجنب الطلبات التي لا نهاية لها عندما لا يتم تحديد قاعدة النطاق

يوفر هذا المثال خطوات التكوين لإرسال طلبات متعددة عند عدم استخدام قاعدة النطاق. يمكن تعيين شرط النهاية بالرجوع إلى المثال 4.1-4.6 لتجنب الطلبات التي لا نهاية لها. تعرض واجهة برمجة تطبيقات REST الاستجابة بالهيكل التالي، وفي هذه الحالة يتم تمثيل عنوان URL للصفحة التالية في paging.next.

{
    "data": [
        {
            "created_time": "2017-12-12T14:12:20+0000",
            "name": "album1",
            "id": "1809938745705498_1809939942372045"
        },
        {
            "created_time": "2017-12-12T14:14:03+0000",
            "name": "album2",
            "id": "1809938745705498_1809941802371859"
        },
        {
            "created_time": "2017-12-12T14:14:11+0000",
            "name": "album3",
            "id": "1809938745705498_1809941879038518"
        }
    ],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "https://graph.facebook.com/me/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
    }
}
...

الاستجابة الأخيرة هي:

{
    "data": [],
    "paging": {
        "cursors": {
            "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
            "before": "NDMyNzQyODI3OTQw"
        },
        "previous": "https://graph.facebook.com/me/albums?limit=25&before=NDMyNzQyODI3OTQw",
        "next": "Same with Last Request URL"
    }
}

الخطوة 1: تعيين قواعد فصل الصفحات كـ "AbsoluteUrl": "$.paging.next".

الخطوة 2: إذا كان next في الاستجابة الأخيرة هو نفسه دائمًا مع عنوان URL الأخير للطلب ولم يكن فارغًا، فسيتم إرسال الطلبات التي لا نهاية لها. يمكن استخدام شرط النهاية لتجنب الطلبات التي لا نهاية لها. لذا، يجب تعيين قاعدة الشرط النهاية بالرجوع إلى المثال 4.1-4.6.

مثال 6: تعيين الحد الأقصى لرقم الطلب لتجنب الطلبات التي لا نهاية لها

تعيين MaxRequestNumber لتجنب الطلبات التي لا نهاية لها كما هو موضح في لقطة الشاشة التالية:

Screenshot showing the Max Request Number setting for Example 6.

مثال 7: يتم دعم قاعدة فصل الصفحات RFC 5988 بشكل افتراضي

ستحصل الواجهة الخلفية تلقائيًا على عنوان URL التالي استنادًا إلى ارتباطات نمط RFC 5988 في الرأس.

Screenshot showing samples of the http header that complies with R F C 5988.

تلميح

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

Screenshot showing how to disable R F C 5988 setting for Example 7.

مثال 8: يكون عنوان URL للطلب التالي من نص الاستجابة عند استخدام فصل الصفحات في تعيين تدفقات البيانات

يوضح هذا المثال كيفية تعيين قاعدة فصل الصفحات وقاعدة شرط النهاية في تعيين تدفقات البيانات عندما يكون عنوان URL للطلب التالي من نص الاستجابة.

يظهر مخطط الاستجابة أدناه:

Screenshot showing the response schema of Example 8.

يجب تعيين قواعد فصل الصفحات مثل لقطة الشاشة التالية:

Screenshot showing how to set the pagination rule for Example 8.

بشكل افتراضي، سيتوقف ترقيم الصفحات عندما يكون النص الأساسي. {@odata.nextLink}** فارغ أو فارغ.

ولكن إذا كانت قيمة @odata.nextLink في نص الاستجابة الأخيرة تساوي عنوان URL الأخير للطلب، فسيؤدي ذلك إلى الحلقة اللانهائية. لتجنب هذا الشرط، حدد قواعد شرط النهاية.

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

مثال 9: تنسيق الاستجابة هو XML وعنوان URL للطلب التالي من نص الاستجابة عند استخدام فصل الصفحات في تعيين تدفقات البيانات

يوضح هذا المثال كيفية تعيين قاعدة فصل الصفحات في تعيين تدفقات البيانات عندما يكون تنسيق الاستجابة هو XML ويكون عنوان URL للطلب التالي من نص الاستجابة. كما هو موضح في لقطة الشاشة التالية، عنوان URL الأول هو https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

Screenshot showing the response format is X M L and the next request U R L is from the response body.

يظهر مخطط الاستجابة أدناه:

Screenshot showing the response schema of Example 9.

صيغة قاعدة فصل الصفحات هي نفسها الواردة في المثال 8 ويجب تعيينها على النحو التالي في هذا المثال:

Screenshot showing setting the pagination rule for Example 9.

قم بتصدير استجابة JSON كas-is

يمكنك استخدام موصل REST هذا لتصدير استجابة REST API JSON كas-is إلى مختلف المتاجر القائمة على الملفات. للوصول إلى هذه النسخة متعددة المخططات، قم بتخطي المقطع "structure" (المسمى أيضاً schema) في مجموعة البيانات وتعيين المخطط في copy activity.

تعيين المخطط

لنسخ البيانات من نقطة نهاية REST إلى مصدر البيانات الجدولي، ارجع إلى تعيين المخطط.

للحصول على قائمة بمخازن البيانات التي تعتمدها Copy Activity كمصادر ومتلقيات في Azure Data Factory، راجع مخازن البيانات المدعومة والتنسيقات.

Share via

نسخ البيانات وتحويلها من نقطة نهاية REST وإليها باستخدامAzure Data Factory

القدرات المدعومة

المتطلبات الأساسية

الشروع في العمل

قم بإنشاء خدمة REST المرتبطة باستخدام واجهة المستخدم

تفاصيل تكوين الموصل

خصائص الخدمة المرتبطة

قم باستخدام المصادقة الأساسية

استخدام المصادقة الرئيسية للخدمة

استخدام مصادقة بيانات اعتماد عميل OAuth2

استخدام مصادقة الهوية المدارة المعينة من قبل النظام

استخدام مصادقة الهوية المدارة المعينة من قبل المستخدم

استخدام رءوس المصادقة

خصائص مجموعة البيانات

خصائص نشاط النسخ

REST كمصدر

REST كمتلقي

تعيين خصائص تدفق البيانات

تحويل المصدر

تحويل المتلقي

نموذج برنامج نصي لتدفق البيانات

مثال 1: المتغيرات في QueryParameters

مثال 2: المتغيرات في AbsoluteUrl

مثال 3: المتغيرات في الرؤوس

مثال 4: المتغيرات موجودة في AbsoluteUrl/QueryParameters/Headers، ولم يتم تحديد متغير النهاية مسبقًا وتعتمد حالة النهاية على الاستجابة

مثال 5: تعيين شرط النهاية لتجنب الطلبات التي لا نهاية لها عندما لا يتم تحديد قاعدة النطاق

مثال 6: تعيين الحد الأقصى لرقم الطلب لتجنب الطلبات التي لا نهاية لها

قم بتصدير استجابة JSON كas-is

تعيين المخطط

الموارد الإضافية

Share via

نسخ البيانات وتحويلها من نقطة نهاية REST وإليها باستخدامAzure Data Factory

القدرات المدعومة

المتطلبات الأساسية

الشروع في العمل

قم بإنشاء خدمة REST المرتبطة باستخدام واجهة المستخدم

تفاصيل تكوين الموصل

خصائص الخدمة المرتبطة

قم باستخدام المصادقة الأساسية

استخدام المصادقة الرئيسية للخدمة

استخدام مصادقة بيانات اعتماد عميل OAuth2

استخدام مصادقة الهوية المدارة المعينة من قبل النظام

استخدام مصادقة الهوية المدارة المعينة من قبل المستخدم

استخدام رءوس المصادقة

خصائص مجموعة البيانات

خصائص نشاط النسخ

REST كمصدر

REST كمتلقي

تعيين خصائص تدفق البيانات

تحويل المصدر

تحويل المتلقي

نموذج برنامج نصي لتدفق البيانات

دعم ترقيم الصفحات

أمثلة على قواعد فصل الصفحات

مثال 1: المتغيرات في QueryParameters

مثال 2: المتغيرات في AbsoluteUrl

مثال 3: المتغيرات في الرؤوس

مثال 4: المتغيرات موجودة في AbsoluteUrl/QueryParameters/Headers، ولم يتم تحديد متغير النهاية مسبقًا وتعتمد حالة النهاية على الاستجابة

مثال 5: تعيين شرط النهاية لتجنب الطلبات التي لا نهاية لها عندما لا يتم تحديد قاعدة النطاق

مثال 6: تعيين الحد الأقصى لرقم الطلب لتجنب الطلبات التي لا نهاية لها

مثال 7: يتم دعم قاعدة فصل الصفحات RFC 5988 بشكل افتراضي

مثال 8: يكون عنوان URL للطلب التالي من نص الاستجابة عند استخدام فصل الصفحات في تعيين تدفقات البيانات

مثال 9: تنسيق الاستجابة هو XML وعنوان URL للطلب التالي من نص الاستجابة عند استخدام فصل الصفحات في تعيين تدفقات البيانات

قم بتصدير استجابة JSON كas-is

تعيين المخطط

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

الموارد الإضافية