مرجع موصل بيانات RestApiPoller لإطار عمل الموصل بدون تعليمات برمجية

لإنشاء موصل RestApiPoller بيانات باستخدام Codeless Connector Framework (CCF)، استخدم هذا المرجع كملحق لواجهة برمجة تطبيقات REST ل Microsoft Sentinel لمستندات موصلات البيانات .

يمثل كل dataConnector منها اتصالا محددا لموصل بيانات Microsoft Sentinel. قد يكون لموصل بيانات واحد اتصالات متعددة، والتي تجلب البيانات من نقاط نهاية مختلفة. يتم استخدام تكوين JSON الذي تم إنشاؤه باستخدام هذا المستند المرجعي لإكمال قالب التوزيع لموصل بيانات CCF.

لمزيد من المعلومات، راجع إنشاء موصل بدون تعليمات برمجية لـ Microsoft Azure Sentinel.

موصلات البيانات - إنشاء أو تحديث

راجع عملية الإنشاء أو التحديث في مستندات واجهة برمجة تطبيقات REST للعثور على أحدث إصدار ثابت أو إصدار معاينة لواجهة برمجة التطبيقات. الفرق بين عملية الإنشاء والتحديث هو أن التحديث يتطلب قيمة etag.

أسلوب PUT

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectors/{{dataConnectorId}}?api-version={{apiVersion}}

معلمات URI

لمزيد من المعلومات حول أحدث إصدار من واجهة برمجة التطبيقات، راجع موصلات البيانات - إنشاء معلمات URI أو تحديثها.

الاسم	‏‏الوصف
معرف اتصال البيانات	يجب أن يكون معرف موصل البيانات اسما فريدا وهو نفس المعلمة `name`في نص الطلب.
اسم مجموعة الموارد	اسم مجموعة الموارد، وليس حساسا لحالة الأحرف.
معرف الاشتراك	معرف الاشتراك الهدف.
اسم مساحة العمل	اسم مساحة العمل، وليس المعرف. نمط Regex: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
إصدار واجهة برمجة التطبيقات	إصدار واجهة برمجة التطبيقات لاستخدامه لهذه العملية.

نص الطلب

يحتوي نص الطلب لموصل RestApiPoller بيانات CCF على البنية التالية:

{
   "name": "{{dataConnectorId}}",
   "kind": "RestApiPoller",
   "etag": "",
   "properties": {
        "connectorDefinitionName": "",
        "auth": {},
        "request": {},
        "response": {},
        "paging": "",
        "dcrConfig": ""
   }
}

RestApiPoller

يمثل RestApiPoller موصل بيانات API Poller CCF حيث تقوم بتخصيص البيانات الأساسية للترحيل والتخويل والطلب/الاستجابة لمصدر البيانات الخاص بك.

الاسم	مطلوبة	نوع	‏‏الوصف
الاسم	صواب	سلسلة	الاسم الفريد للاتصال المطابق لمعلمة URI
النوع	صواب	سلسلة	يجب أن يكون`RestApiPoller`
etag		Guid	اتركها فارغة لإنشاء موصلات جديدة. لعمليات التحديث، يجب أن يتطابق etag مع etag للموصل الموجود (GUID).
properties.connectorDefinitionName		سلسلة	اسم مورد DataConnectorDefinition الذي يعرف تكوين واجهة المستخدم لموصل البيانات. لمزيد من المعلومات، راجع تعريف موصل البيانات.
خصائص.المصادقه	صواب	JSON المتداخل	وصف خصائص المصادقة لاستقصاء البيانات. لمزيد من المعلومات، راجع تكوين المصادقة.
خصائص.طلب	صواب	JSON المتداخل	وصف حمولة الطلب لاستقصاء البيانات، مثل نقطة نهاية واجهة برمجة التطبيقات. لمزيد من المعلومات، راجع تكوين الطلب.
خصائص.استجابه	صواب	JSON المتداخل	وصف عنصر الاستجابة والرسالة المتداخلة التي جرى إرجاعها من واجهة برمجة التطبيقات عند استقصاء البيانات. لمزيد من المعلومات، راجع تكوين الاستجابة.
خصائص.ترحيل الصفحات		JSON المتداخل	وصف حمولة فصل الصفحات عند استقصاء البيانات. لمزيد من المعلومات، راجع تكوين الترحيل.
خصائص.تكوين dcr		JSON المتداخل	المعلمات المطلوبة عند إرسال البيانات إلى قاعدة تجميع البيانات (DCR). لمزيد من المعلومات، راجع تكوين DCR.

تكوين المصادقة

يدعم CCF أنواع المصادقة التالية:

أساسي
مفتاح واجهة برمجة التطبيقات
OAuth2
JWT

إشعار

لا يدعم تنفيذ CCF OAuth2 بيانات اعتماد شهادة العميل.

كأفضل ممارسة، استخدم المعلمات في قسم المصادقة بدلا من بيانات اعتماد الترميز الثابت. لمزيد من المعلومات، راجع إدخال سري آمن.

لإنشاء قالب التوزيع الذي يستخدم المعلمات أيضا، تحتاج إلى إلغاء المعلمات في هذا القسم ببدء [إضافي . يسمح هذا للمعلمات بتعيين قيمة استنادا إلى تفاعل المستخدم مع الموصل. لمزيد من المعلومات، راجع أحرف إلغاء تعبيرات القالب.

لتمكين إدخال بيانات الاعتماد من واجهة المستخدم، connectorUIConfig يتطلب instructions القسم المعلمات المطلوبة. لمزيد من المعلومات، راجع مرجع تعريفات موصل البيانات لإطار عمل الموصل بدون تعليمات برمجية.

المصادقة الأساسية

الحقل	مطلوبة	نوع
اسم المستخدم	صواب	سلسلة
كلمة المرور	صواب	سلسلة

مثال المصادقة الأساسية باستخدام المعلمات المحددة في connectorUIconfig:

"auth": {
    "type": "Basic",
    "UserName": "[[parameters('username')]",
    "Password": "[[parameters('password')]"
}

مفتاح واجهة برمجة التطبيقات

الحقل	مطلوبة	نوع	‏‏الوصف	القيمة الافتراضية
مفتاح واجهة برمجة التطبيقات	صواب	سلسلة	مفتاح سر المستخدم
ApiKeyName		سلسلة	اسم عنوان Uri الذي يحتوي على قيمة ApiKey	`Authorization`
ApiKeyIdentifier		سلسلة	قيمة السلسلة لإبقاء الرمز المميز مسبقا	`token`
IsApiKeyInPostPayload		منطقيه	إرسال البيانات السرية في نص POST بدلا من العنوان	`false`

أمثلة مصادقة APIKey:

"auth": {
    "type": "APIKey",
    "ApiKey": "[[parameters('apikey')]",
    "ApiKeyName": "X-MyApp-Auth-Header",
    "ApiKeyIdentifier": "Bearer"
}

ينتج عن هذا المثال السر المعرف من إدخال المستخدم المرسل في العنوان التالي: X-MyApp-Auth-Header: Bearer apikey

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
}

يستخدم هذا المثال القيم الافتراضية والنتائج في العنوان التالي: التخويل: الرمز المميز 123123123

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
    "ApiKeyName": ""
}

ApiKeyName نظرا لتعيين بشكل صريح إلى ""، فإن النتيجة هي العنوان التالي: التخويل: 123123123

OAuth2

يدعم Codeless Connector Framework منح رمز التخويل OAuth 2.0 وبيانات اعتماد العميل. يستخدم العميل العام والسري نوع منح "رمز التخويل" لتبادل رمز التخويل للرمز المميز للوصول. بعد عودة المستخدم إلى العميل عبر عنوان URL لإعادة التوجيه، سيحصل التطبيق على رمز التخويل من عنوان URL ويستخدمه لطلب الرمز المميز للوصول.

الحقل	مطلوبة	نوع	‏‏الوصف
معرف العميل	صواب	السلسلة‬	معرف العميل
ClientSecret	صواب	السلسلة‬	سر العميل
رمز التخويل	صواب عند grantType = `authorization_code`	السلسلة‬	إذا كان نوع المنحة عبارة `authorization_code` عن قيمة الحقل هذه، فسيكون رمز التخويل الذي يتم إرجاعه من خدمة المصادقة.
النطاق	صواب لنوع المنحة `authorization_code` اختياري لنوع المنحة `client_credentials`	السلسلة‬	قائمة نطاقات مفصولة بمسافة لموافقة المستخدم. لمزيد من المعلومات، راجع نطاقات وأذونات OAuth2.
RedirectUri	صواب عند grantType = `authorization_code`	السلسلة‬	يجب أن يكون عنوان URL لإعادة التوجيه `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`
نوع المنحة	صواب	السلسلة‬	`authorization_code` أو `client_credentials`
نقطة نهاية الرمز المميز	صواب	السلسلة‬	عنوان URL لتبادل التعليمات البرمجية برمز مميز صالح في `authorization_code` المنحة أو معرف العميل والسر مع رمز مميز صالح في `client_credentials` المنحة.
عناوين نقاط النهاية المميزة		‏‏الكائن	كائن قيمة مفتاح اختياري لإرسال رؤوس مخصصة إلى خادم الرمز المميز
معلمات الاستعلام عن نقاط النهاية المميزة		‏‏الكائن	كائن قيمة مفتاح اختياري لإرسال معلمات استعلام مخصصة إلى خادم الرمز المميز
نقطة نهاية التخويل	صواب	السلسلة‬	URL لموافقة المستخدم على `authorization_code` التدفق
عناوين نقاط النهاية للتخويل		‏‏الكائن	كائن قيمة مفتاح اختياري لإرسال رؤوس مخصصة إلى خادم المصادقة
معلمات AuthorizationEndpointQuery		‏‏الكائن	زوج قيمة مفتاح اختياري مستخدم في طلب تدفق رمز التخويل OAuth2

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

مثال: نوع منح OAuth2 authorization_code

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "authorizationEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/authorize",
    "authorizationEndpointHeaders": {},
    "authorizationEndpointQueryParameters": {
        "prompt": "consent"
    },
    "redirectUri": "https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "authorization_code"
}

مثال: نوع منح OAuth2 client_credentials

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "client_credentials"
}

JWT

تدعم مصادقة JSON Web Token (JWT) الحصول على الرموز المميزة عبر بيانات اعتماد اسم المستخدم/كلمة المرور واستخدامها لطلبات واجهة برمجة التطبيقات.

مثال أساسي:

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password", 
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://token_endpoint.contoso.com",
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}

بيانات الاعتماد في نص POST (افتراضي):

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password",
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://api.example.com/token",
    "Headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    "IsCredentialsInHeaders": false,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}

بيانات الاعتماد في الرؤوس (المصادقة الأساسية):

"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "client_id",
        "value": "[[parameters('ClientId')]"
    },
    "password": {
        "key": "client_secret",
        "value": "[[parameters('ClientSecret')]"
    },
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "IsCredentialsInHeaders": true,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token",
    "RequestTimeoutInSeconds": 30
}

بيانات الاعتماد في الرؤوس (رمز المستخدم المميز):

"auth": {
    "type": "JwtToken",
    "UserToken": "[[parameters('userToken')]",
    "UserTokenPrepend": "Bearer",
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "TokenEndpointHttpMethod": "GET",
    "NoAccessTokenPrepend": true,
    "JwtTokenJsonPath": "$.systemToken"
}

تدفق المصادقة:

إرسال بيانات الاعتماد إلى TokenEndpoint للحصول على رمز JWT المميز
- إذا : IsCredentialsInHeaders: trueيرسل عنوان المصادقة الأساسية باسم المستخدم:كلمة المرور
- إذا : IsCredentialsInHeaders: falseيرسل بيانات الاعتماد في نص POST
استخراج الرمز المميز باستخدام JwtTokenJsonPath أو من عنوان الاستجابة
استخدام الرمز المميز في طلبات واجهة برمجة التطبيقات اللاحقة مع ApiKeyName العنوان

خصائص:

الحقل	مطلوبة	نوع	‏‏الوصف
النوع	صواب	السلسلة‬	يجب أن يكون`JwtToken`
"اسم المستخدم"	True (إذا لم يتم استخدام userToken )	‏‏الكائن	زوج قيم المفاتيح لبيانات اعتماد اسم المستخدم. إذا `userName` تم إرسال و `password` في طلب العنوان، فحدد الخاصية `value` باسم المستخدم. إذا `userName` وأرسل `password` في طلب النص الأساسي، فحدد `Key` و `Value`
كلمة المرور	True (إذا لم يتم استخدام userToken )	‏‏الكائن	زوج قيمة المفتاح لبيانات اعتماد كلمة المرور. إذا `userName` تم إرسال و `password` في طلب العنوان، فحدد الخاصية `value` باسم المستخدم. إذا `userName` وأرسل `password` في طلب النص الأساسي، فحدد `Key` و `Value`
رمز المستخدم المميز	True (إذا لم يتم استخدام userName )	السلسلة‬	رمز المستخدم المميز الذي أنشأه العميل للحصول على رمز مميز للنظام للمصادقة
UserTokenPrepend	خطأ	السلسلة‬	إلحاق النص قبل الرمز المميز. مثال: `Bearer`
NoAccessTokenPrepend	خطأ	قيمة منطقية	يجب ألا يتم إلحاق أي شيء بعلامة الوصول للإشارة إلى الرمز المميز
TokenEndpointHttpMethod	خطأ	السلسلة‬	أسلوب HTTP إلى نقطة نهاية الرمز المميز. يمكن أن يكون `Get`، أو `Post`. افتراضي: `Post`
نقطة نهاية الرمز المميز	صواب	السلسلة‬	نقطة نهاية URL للحصول على رمز JWT المميز
IsCredentialsInHeaders		قيمة منطقية	إرسال بيانات الاعتماد كعنوان المصادقة الأساسية (`true`) مقابل نص POST (`false`). افتراضي: `false`
طلب IsJson		قيمة منطقية	إرسال الطلب ك JSON (العنوان `Content-Type = application/json`) مقابل ترميز النموذج (العنوان `Content-Type = application/x-www-form-urlencoded`). افتراضي: `false`
مسار JwtTokenJson		السلسلة‬	JSONPath لاستخراج الرمز المميز من الاستجابة (على سبيل المثال، "`$.access_token`")
JwtTokenInResponseHeader		قيمة منطقية	استخراج الرمز المميز من رأس الاستجابة مقابل النص الأساسي. افتراضي: `false`
JwtTokenHeaderName		السلسلة‬	اسم الرأس عندما يكون الرمز المميز في عنوان الاستجابة. الافتراضي: "`Authorization`"
JwtTokenIdentifier		السلسلة‬	المعرف المستخدم لاستخراج JWT من سلسلة رمز مميز مسبوقة
معلمات الاستعلام		‏‏الكائن	معلمات الاستعلام المخصصة لتضمينها عند إرسال الطلب إلى نقطة نهاية الرمز المميز
رؤوس		‏‏الكائن	عناوين مخصصة لتضمينها عند إرسال الطلب إلى نقطة نهاية الرمز المميز
RequestTimeoutInSeconds		رقم صحيح	طلب المهلة بالثوان. الافتراضي: `100`، الحد الأقصى `180`

تدفق المصادقة:

إرسال بيانات الاعتماد إلى TokenEndpoint للحصول على رمز JWT المميز
- إذا : IsCredentialsInHeaders: trueيرسل عنوان المصادقة الأساسية باسم المستخدم:كلمة المرور
- إذا : IsCredentialsInHeaders: falseيرسل بيانات الاعتماد في نص POST
استخراج الرمز المميز باستخدام JwtTokenJsonPath أو من عنوان الاستجابة
استخدام الرمز المميز في طلبات واجهة برمجة التطبيقات اللاحقة مع ApiKeyName العنوان

إشعار

القيود:

يتطلب مصادقة اسم المستخدم/كلمة المرور للحصول على الرمز المميز
لا يدعم طلبات الرمز المميز المستندة إلى مفتاح API
مصادقة الرأس المخصصة (بدون اسم المستخدم/كلمة المرور) غير مدعومة

تكوين الطلب

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

الحقل	مطلوبة	نوع	‏‏الوصف
نقطة نهاية Api	صواب	السلسلة‬	عنوان URL للخادم البعيد. يحدد نقطة النهاية لسحب البيانات منها.
RateLimitQPS		رقم صحيح	يحدد عدد الاستدعاءات أو الاستعلامات المسموح بها في ثانية واحدة.
RateLimitConfig		‏‏الكائن	يحدد تكوين حد المعدل لواجهة برمجة تطبيقات RESTful. راجع المثال.
QueryWindowInMin		رقم صحيح	تعريف نافذة الاستعلام المتوفرة في دقائق. الحد الأدنى هو دقيقة واحدة. الوقت الافتراضي هو 5 دقائق.
HttpMethod		السلسلة‬	تعريف أسلوب API: `GET`(افتراضي) أو `POST`
تنسيق وقت الاستعلام		السلسلة‬	يحدد تنسيق التاريخ والوقت الذي تتوقعه نقطة النهاية (الخادم البعيد). يستخدم CCF التاريخ والوقت الحاليين أينما يتم استخدام هذا المتغير. القيم المحتملة هي الثوابت: `UnixTimestamp`، `UnixTimestampInMills` أو أي تمثيل صالح آخر لوقت التاريخ، على سبيل المثال: `yyyy-MM-dd`، `MM/dd/yyyy HH:mm:ss` الافتراضي هو ISO 8601 UTC
إعادة المحاولة		عدد صحيح (1...6)	`1` `6` تعريف لإعادة المحاولة المسموح لها بالتعافي من الفشل. القيمة الافتراضية هي `3`.
المهلةInSeconds		عدد صحيح (1...180)	يحدد مهلة الطلب، بالثواني. القيمة الافتراضية هي `20`
IsPostPayloadJson		قيمة منطقية	يحدد ما إذا كانت حمولة POST بتنسيق JSON. القيمة الافتراضية هي `false`
رؤوس		‏‏الكائن	أزواج القيمة الرئيسية التي تحدد عناوين الطلب.
معلمات الاستعلام		‏‏الكائن	أزواج القيمة الرئيسية التي تحدد معلمات استعلام الطلب.
StartTimeAttributeName	صواب عند `EndTimeAttributeName` تعيين	السلسلة‬	تعريف اسم معلمة الاستعلام لوقت بدء الاستعلام. راجع المثال.
EndTimeAttributeName	صواب عند `StartTimeAttributeName` تعيين	السلسلة‬	تعريف اسم معلمة الاستعلام لوقت انتهاء الاستعلام.
QueryTimeIntervalAttributeName		السلسلة‬	إذا كانت نقطة النهاية تتطلب تنسيقا متخصصا للاستعلام عن البيانات في إطار زمني، فاستخدم هذه الخاصية مع `QueryTimeIntervalPrepend` المعلمتين و `QueryTimeIntervalDelimiter` . راجع المثال.
QueryTimeIntervalPrepend	صواب عند `QueryTimeIntervalAttributeName` تعيين	السلسلة‬	راجع `QueryTimeIntervalAttributeName`
QueryTimeIntervalDelimiter	صواب عند `QueryTimeIntervalAttributeName` تعيين	السلسلة‬	راجع `QueryTimeIntervalAttributeName`
QueryParametersTemplate		السلسلة‬	قالب الاستعلام لاستخدامه عند تمرير المعلمات في سيناريوهات متقدمة. br>على سبيل المثال: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`

عندما تتطلب واجهة برمجة التطبيقات معلمات معقدة، استخدم queryParameters أو queryParametersTemplate التي تتضمن بعض المتغيرات المضمنة.

متغير مضمن	للاستخدام في `queryParameters`	للاستخدام في `queryParametersTemplate`
`_QueryWindowStartTime`	نعم	نعم
`_QueryWindowEndTime`	نعم	نعم
`_APIKeyName`	لا	نعم
`_APIKey`	لا	نعم

مثال StartTimeAttributeName

فكِّر في هذا المثال:

StartTimeAttributeName = from
EndTimeAttributeName = until
ApiEndpoint = https://www.example.com

الاستعلام المرسل إلى الخادم البعيد هو: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}

مثال QueryTimeIntervalAttributeName

فكِّر في هذا المثال:

QueryTimeIntervalAttributeName = interval
QueryTimeIntervalPrepend = time:
QueryTimeIntervalDelimiter = ..
ApiEndpoint = https://www.example.com

الاستعلام المرسل إلى الخادم البعيد هو: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}

مثال على RateLimitConfig

فكِّر في هذا المثال:

ApiEndpoint = https://www.example.com

"rateLimitConfig": {
  "evaluation": {
    "checkMode": "OnlyWhen429"
  },
  "extraction": {
    "source": "CustomHeaders",
    "headers": {
      "limit": {
        "name": "X-RateLimit-Limit",
        "format": "Integer"
      },
      "remaining": {
        "name": "X-RateLimit-Remaining",
        "format": "Integer"
      },
      "reset": {
        "name": "X-RateLimit-RetryAfter",
        "format": "UnixTimeSeconds"
      }
    }
  },
  "retryStrategy": {
    "useResetOrRetryAfterHeaders": true
  }
}

عندما يتضمن الرد رؤوس حد المعدل، يمكن للموصل استخدام هذه المعلومات لتعديل معدل الطلب.

طلب أمثلة باستخدام Microsoft Graph كواجهة برمجة تطبيقات مصدر بيانات

يستعلم هذا المثال عن الرسائل باستخدام معلمة استعلام عامل تصفية. لمزيد من المعلومات، راجع معلمات استعلام Microsoft Graph API.

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
    "User-Agent": "Example-app-agent"
  },
  "QueryTimeIntervalAttributeName": "filter",
  "QueryTimeIntervalPrepend": "receivedDateTime gt ",
  "QueryTimeIntervalDelimiter": " and receivedDateTime lt "
}

يرسل GET المثال السابق طلبا إلى https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. يتم تحديث الطابع الزمني لكل queryWindowInMin مرة.

يتم تحقيق نفس النتائج مع هذا المثال:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "queryParameters": {
    "filter": "receivedDateTime gt {_QueryWindowStartTime} and receivedDateTime lt {_QueryWindowEndTime}"
  }
}

خيار آخر هو عندما يتوقع مصدر البيانات معلمتين للاستعلام، واحدة لوقت البدء وواحدة لوقت الانتهاء.

مثال:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/calendarView",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "StartTimeAttributeName": "startDateTime",
  "EndTimeAttributeName": "endDateTime",
}

يؤدي هذا إلى إرسال GET طلب إلى https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

بالنسبة للاستعلامات المعقدة، استخدم QueryParametersTemplate. يرسل POST هذا المثال التالي طلبا مع معلمات في النص الأساسي.

مثال:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "POST",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "isPostPayloadJson": true,
  "queryParametersTemplate": "{\"query":"TableName | where createdTimestamp between (datetime({_QueryWindowStartTime}) .. datetime({_QueryWindowEndTime}))\"}"
}

تكوين الاستجابة

حدد معالجة الاستجابة لموصل البيانات الخاص بك باستخدام المعلمات التالية:

الحقل	مطلوبة	نوع	‏‏الوصف
EventsJsonPaths	صواب	قائمة السلاسل	يحدد المسار إلى الرسالة في استجابة JSON. يحدد تعبير مسار JSON مسارًا إلى عنصر أو مجموعة من العناصر في بنية JSON
SuccessStatusJsonPath		السلسلة‬	يحدد المسار إلى رسالة النجاح في الاستجابة JSON. عند تعريف هذه المعلمة، يجب أيضا تعريف المعلمة `SuccessStatusValue` .
SuccessStatusValue		السلسلة‬	يحدد المسار إلى قيمة رسالة النجاح في الاستجابة JSON
IsGzipCompressed		قيمة منطقية	تحديد ما إذا كانت الاستجابة مضغوطة في ملف gzip
تنسيق	صواب	السلسلة‬	`json` أو `csv` أو `xml`
الضغطالجو		السلسلة‬	خوارزمية الضغطات، إما `multi-gzip` أو `deflate`. بالنسبة لخوارزمية ضغط gzip، ما عليك سوى التكوين `IsGzipCompressed` إلى `True` بدلا من تعيين قيمة لهذه المعلمة.
CsvDelimiter		السلسلة‬	إذا كان تنسيق الاستجابة CSV وتريد تغيير محدد CSV الافتراضي ل `","`
HasCsvBoundary		قيمة منطقية	الإشارة إلى ما إذا كانت بيانات CSV تحتوي على حد
HasCsvHeader		قيمة منطقية	الإشارة إلى ما إذا كانت بيانات CSV تحتوي على رأس، فإن الإعداد الافتراضي هو `True`
CsvEscape		السلسلة‬	حرف الإلغاء لحدود الحقل، الافتراضي هو `"` على سبيل المثال، يتطلب `id,name,avg` CSV مع رؤوس `1,"my name",5.5` وصف من البيانات التي تحتوي على مسافات مثل `"` حد الحقل.
ConvertChildPropertiesToArray		قيمة منطقية	حالة خاصة يقوم فيها الخادم البعيد بإرجاع كائن بدلا من قائمة الأحداث حيث تحتوي كل خاصية على بيانات فيه.

إشعار

يتم تحليل نوع تنسيق CSV حسب مواصفات RFC4180 .

أمثلة تكوين الاستجابة

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

"response": {
  "EventsJsonPaths ": ["$.value"],
  "format": "json",
  "SuccessStatusJsonPath": "$.status",
  "SuccessStatusValue": "success",
  "IsGzipCompressed": true
 }

تستعد الاستجابة المتوقعة في هذا المثال ل CSV بدون عنوان.

"response": {
  "EventsJsonPaths ": ["$"],
  "format": "csv",
  "HasCsvHeader": false
 }

تكوين الترحيل

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

نوع الترحيل	عامل القرار
عنوان الارتباط PersistentLinkHeader NextPageUrl	هل تحتوي استجابة واجهة برمجة التطبيقات على ارتباطات إلى الصفحات التالية والسابقة؟
NextPageToken الرمز المميز الثابت	هل تحتوي استجابة واجهة برمجة التطبيقات على رمز مميز أو مؤشر للصفحتين التالية والسابقة؟
اوفست	هل تدعم استجابة واجهة برمجة التطبيقات معلمة لعدد الكائنات التي يجب تخطيها عند الترحيل؟
CountBasedPaging	هل تدعم استجابة واجهة برمجة التطبيقات معلمة لعدد العناصر التي يجب إرجاعها؟

تكوين LinkHeader أو PersistentLinkHeader

نوع الترحيل الأكثر شيوعا هو عندما توفر واجهة برمجة تطبيقات مصدر بيانات الخادم عناوين URL للصفحات التالية والسابقة من البيانات. لمزيد من المعلومات حول مواصفات رأس الارتباط، راجع RFC 5988.

LinkHeader الترحيل يعني أن استجابة واجهة برمجة التطبيقات تتضمن إما:

رأس استجابة Link HTTP
أو مسار JSON لاسترداد الارتباط من نص الاستجابة.

PersistentLinkHeader الترحيل له نفس خصائص LinkHeader، باستثناء أن عنوان الارتباط يستمر في تخزين الواجهة الخلفية. يتيح هذا الخيار ارتباطات الترحيل عبر نوافذ الاستعلام. على سبيل المثال، لا تدعم بعض واجهات برمجة التطبيقات أوقات بدء الاستعلام أو أوقات الانتهاء. بدلا من ذلك، فإنها تدعم مؤشر جانب الخادم. يمكن استخدام أنواع الصفحات الثابتة لتذكر مؤشر جانب الخادم. لمزيد من المعلومات، راجع ما هو المؤشر؟.

إشعار

يمكن أن يكون هناك استعلام واحد فقط قيد التشغيل للموصل مع PersistentLinkHeader لتجنب حالات السباق على المؤشر من جانب الخادم. قد يؤثر هذا على زمن الانتقال.

الحقل	مطلوبة	نوع	‏‏الوصف
LinkHeaderTokenJsonPath	خطأ	السلسلة‬	استخدم هذه الخاصية للإشارة إلى مكان الحصول على القيمة في نص الاستجابة. على سبيل المثال، إذا أرجع مصدر البيانات JSON التالي: `{ nextPage: "foo", value: [{data}]}` فسيكون `LinkHeaderTokenJsonPath$.nextPage`
حجم الصفحات	خطأ	رقم صحيح	عدد الأحداث لكل صفحة
PageSizeParameterName	خطأ	السلسلة‬	اسم معلمة الاستعلام لحجم الصفحة
صفحة معلومات التوزيع	خطأ	السلسلة‬	كيف يتم ملء معلومات البلاغ. يقبل إما "QueryString" أو "RequestBody"
PagingQueryParamOnly	خطأ	قيمة منطقية	إذا تم تعيينه على true، سيتم حذف جميع معلمات الاستعلام الأخرى باستثناء معاملات الاستعلام المرحلية.

إليك بعض الأمثلة:

"paging": {
  "pagingType": "LinkHeader",
  "linkHeaderTokenJsonPath" : "$.metadata.links.next"
}

"paging": {
 "pagingType" : "PersistentLinkHeader", 
 "pageSizeParameterName" : "limit", 
 "pageSize" : 500 
}

تكوين NextPageUrl

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

الحقل	مطلوبة	نوع	‏‏الوصف
حجم الصفحات	خطأ	رقم صحيح	عدد الأحداث لكل صفحة
PageSizeParameterName	خطأ	السلسلة‬	اسم معلمة الاستعلام لحجم الصفحة
NextPageUrl	خطأ	السلسلة‬	فقط إذا كان الموصل ل Coralogix API
NextPageUrlQueryParameters	خطأ	أزواج قيمة مفتاح الكائن - إضافة معلمة استعلام مخصصة إلى كل طلب للصفحة التالية
NextPageParaName	خطأ	السلسلة‬	يحدد اسم "الصفحة التالية" في الطلب.
HasNextFlagJsonPath	خطأ	السلسلة‬	تعريف المسار إلى سمة علامة HasNextPage
NextPageRequestHeader	خطأ	السلسلة‬	يحدد عنوان "الصفحة التالية" في الطلب.
NextPageUrlQueryParametersTemplate	خطأ	السلسلة‬	فقط إذا كان الموصل ل Coralogix API
صفحة معلومات التوزيع	خطأ	السلسلة‬	كيف يتم ملء معلومات البلاغ. يقبل إما "QueryString" أو "RequestBody"
PagingQueryParamOnly	خطأ	قيمة منطقية	إذا تم تعيينه على true، سيتم حذف جميع معلمات الاستعلام الأخرى باستثناء معاملات الاستعلام المرحلية.

مثال:

"paging": {
 "pagingType" : "NextPageUrl", 
  "nextPageTokenJsonPath" : "$.data.repository.pageInfo.endCursor", 
  "hasNextFlagJsonPath" : "$.data.repository.pageInfo.hasNextPage", 
  "nextPageUrl" : "https://api.github.com/graphql", 
  "nextPageUrlQueryParametersTemplate" : "{'query':'query{repository(owner:\"xyz\")}" 
}

تكوين NextPageToken أو PersistentToken

NextPageToken يستخدم ترقيم الصفحات رمزا مميزا (تجزئة أو مؤشر) يمثل حالة الصفحة الحالية. يتم تضمين الرمز المميز في استجابة واجهة برمجة التطبيقات، ويلحقه العميل بالطلب التالي لجلب الصفحة التالية. غالبا ما يتم استخدام هذا الأسلوب عندما يحتاج الخادم إلى الحفاظ على الحالة الدقيقة بين الطلبات.

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

الحقل	مطلوبة	نوع	‏‏الوصف
حجم الصفحات	خطأ	رقم صحيح	عدد الأحداث لكل صفحة
PageSizeParameterName	خطأ	سلسلة	اسم معلمة الاستعلام لحجم الصفحة
NextPageTokenJsonPath	خطأ	سلسلة	مسار JSON للرمز المميز للصفحة التالية في نص الاستجابة.
NextPageTokenResponseHeader	خطأ	سلسلة	إذا كان `NextPageTokenJsonPath` فارغا، فاستخدم الرمز المميز في اسم الرأس هذا للصفحة التالية.
NextPageParaName	خطأ	سلسلة	يحدد اسم "الصفحة التالية" في الطلب.
HasNextFlagJsonPath	خطأ	سلسلة	يحدد المسار إلى سمة علامة HasNextPage عند تحديد ما إذا كان هناك المزيد من الصفحات المتبقية في الاستجابة.
NextPageRequestHeader	خطأ	سلسلة	يحدد عنوان "الصفحة التالية" في الطلب.
صفحة معلومات التوزيع	خطأ	السلسلة‬	كيف يتم ملء معلومات البلاغ. يقبل إما "QueryString" أو "RequestBody"
PagingQueryParamOnly	خطأ	قيمة منطقية	إذا تم تعيينه على true، سيتم حذف جميع معلمات الاستعلام الأخرى باستثناء معاملات الاستعلام المرحلية.

أمثلة:

"paging": {
 "pagingType" : "NextPageToken", 
 "nextPageRequestHeader" : "ETag", 
 "nextPageTokenResponseHeader" : "ETag" 
}

"paging": {
 "pagingType" : "PersistentToken", 
    "nextPageParaName" : "gta", 
    "nextPageTokenJsonPath" : "$.alerts[-1:]._id" 
}

تكوين الإزاحة

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

الحقل	مطلوبة	نوع	‏‏الوصف
حجم الصفحات	خطأ	رقم صحيح	عدد الأحداث لكل صفحة
PageSizeParameterName	خطأ	السلسلة‬	اسم معلمة الاستعلام لحجم الصفحة
OffsetParaName	خطأ	السلسلة‬	اسم معلمة استعلام الطلب التالي. يحسب CCF قيمة الإزاحة لكل طلب، (جميع الأحداث التي تم استيعابها + 1)
صفحة معلومات التوزيع	خطأ	السلسلة‬	كيف يتم ملء معلومات البلاغ. يقبل إما "QueryString" أو "RequestBody"
PagingQueryParamOnly	خطأ	قيمة منطقية	إذا تم تعيينه على true، سيتم حذف جميع معلمات الاستعلام الأخرى باستثناء معاملات الاستعلام المرحلية.

مثال:

"paging": {
  "pagingType": "Offset", 
  "offsetParaName": "offset",
  "pageSize": 50,
  "pagingQueryParamOnly": true,
  "pagingInfoPlacement": "QueryString"
}

تكوين CountBasedPaging

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

الحقل	مطلوبة	نوع	‏‏الوصف
pageNumberParaName	صواب	السلسلة‬	اسم المعلمة لرقم الصفحة في طلب HTTP
حجم الصفحات	خطأ	رقم صحيح	عدد الأحداث لكل صفحة
ZeroBasedIndexing	خطأ	قيمة منطقية	وضع علامة للإشارة إلى ما إذا كان العدد يستند إلى صفر
HasNextFlagJsonPath	خطأ	السلسلة‬	مسار JSON للإشارة في حمولة استجابة HTTP للإشارة إلى وجود المزيد من الصفحات
TotalResultsJsonPath	خطأ	السلسلة‬	مسار JSON لإجمالي عدد النتائج في حمولة استجابة HTTP
PageNumberJsonPath	خطأ	السلسلة‬	مطلوب إذا تم توفير totalResultsJsonPath. مسار JSON لرقم الصفحة في حمولة استجابة HTTP
PageCountJsonPath	خطأ	السلسلة‬	مطلوب إذا تم توفير totalResultsJsonPath. مسار JSON لعدد الصفحات في حمولة استجابة HTTP
صفحة معلومات التوزيع	خطأ	السلسلة‬	كيف يتم ملء معلومات البلاغ. يقبل إما "QueryString" أو "RequestBody"
PagingQueryParamOnly	خطأ	قيمة منطقية	إذا تم تعيينه على true، سيتم حذف جميع معلمات الاستعلام الأخرى باستثناء معاملات الاستعلام المرحلية.

مثال:

"paging": {
 "pagingType" : "CountBasedPaging", 
 "pageNumberParaName" : "page", 
 "pageSize" : 10, 
 "zeroBasedIndexing" : true, 
 "hasNextFlagJsonPath" : "$.hasNext", 
 "totalResultsJsonPath" : "$.totalResults", 
 "pageNumberJsonPath" : "$.pageNumber", 
 "pageCountJsonPath" : "$.pageCount"
}

تكوين DCR

الحقل	مطلوبة	نوع	‏‏الوصف
نقطة نهاية تجميع البيانات	صواب	السلسلة‬	DCE (نقطة نهاية تجميع البيانات) على سبيل المثال: `https://example.ingest.monitor.azure.com`.
DataCollectionRuleImmutableId	صواب	السلسلة‬	معرف DCR غير القابل للتغيير. ابحث عنه عن طريق عرض استجابة إنشاء DCR أو باستخدام واجهة برمجة تطبيقات DCR
اسم الدفق	صواب	سلسلة	هذه القيمة هي `streamDeclaration` المحددة في DCR (يجب أن تبدأ البادئة ب Custom-)

مثال على موصل بيانات CCF

فيما يلي مثال على جميع مكونات موصل بيانات CCF JSON معا.

{
   "kind": "RestApiPoller",
   "properties": {
      "connectorDefinitionName": "ConnectorDefinitionExample",
      "dcrConfig": {
           "streamName": "Custom-ExampleConnectorInput",
           "dataCollectionEndpoint": "https://example-dce-sbsr.location.ingest.monitor.azure.com",
           "dataCollectionRuleImmutableId": "dcr-32_character_hexadecimal_id"
            },
      "dataType": "ExampleLogs",
      "auth": {
         "type": "Basic",
         "password": "[[parameters('username')]",
         "userName": "[[parameters('password')]"
      },
      "request": {
         "apiEndpoint": "https://rest.contoso.com/example",
         "rateLimitQPS": 10,
         "rateLimitConfig": {
            "evaluation": {
              "checkMode": "OnlyWhen429"
            },
            "extraction": {
              "source": "CustomHeaders",
              "headers": {
                "limit": {
                  "name": "X-RateLimit-Limit",
                  "format": "Integer"
                },
                "remaining": {
                  "name": "X-RateLimit-Remaining",
                  "format": "Integer"
                },
                "reset": {
                  "name": "X-RateLimit-RetryAfter",
                  "format": "UnixTimeSeconds"
                }
              }
            },
            "retryStrategy": {
              "useResetOrRetryAfterHeaders": true
            }
         },
         "queryWindowInMin": 5,
         "httpMethod": "POST",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader",
         "pagingInfoPlacement": "RequestBody",
         "pagingQueryParamOnly": true
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}

الملاحظات

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

Last updated on 2025-12-11

مشاركة عبر

مرجع موصل بيانات RestApiPoller لإطار عمل الموصل بدون تعليمات برمجية

موصلات البيانات - إنشاء أو تحديث

معلمات URI

نص الطلب

RestApiPoller

تكوين المصادقة

المصادقة الأساسية

مفتاح واجهة برمجة التطبيقات

OAuth2

JWT

تكوين الطلب

مثال StartTimeAttributeName

مثال QueryTimeIntervalAttributeName

مثال على RateLimitConfig

طلب أمثلة باستخدام Microsoft Graph كواجهة برمجة تطبيقات مصدر بيانات

تكوين الاستجابة

أمثلة تكوين الاستجابة

تكوين الترحيل

تكوين LinkHeader أو PersistentLinkHeader

تكوين NextPageUrl

تكوين NextPageToken أو PersistentToken

تكوين الإزاحة

تكوين CountBasedPaging

تكوين DCR

مثال على موصل بيانات CCF

الملاحظات

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