مرجع موصل بيانات RestApiPoller للنظام الأساسي للموصل بدون تعليمات برمجية

مقالة
09/30/2024

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

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

لمزيد من المعلومات، راجع إنشاء موصل بدون تعليمات برمجية لـ 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	‏‏الوصف
معرف اتصال البيانات	يجب أن يكون معرف موصل البيانات اسما فريدا وهو نفس المعلمة `name` في نص الطلب.
resourceGroupName	اسم مجموعة الموارد، وليس حساسا لحالة الأحرف.
subscriptionId	معرف الاشتراك الهدف.
اسم مساحة العمل	اسم مساحة العمل، وليس المعرف. نمط Regex: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
إصدار واجهة برمجة التطبيقات	إصدار واجهة برمجة التطبيقات لاستخدامه لهذه العملية.

نص الطلب

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

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

RestApiPoller

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

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

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

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

أساسي
APIKey
OAuth2
Jwt

إشعار

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

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

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

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

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

الحقل	المطلوب	نوع
UserName	صواب	سلسلة
كلمة المرور	صواب	سلسلة

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

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

APIKey

الحقل	المطلوب	نوع	الوصف	القيمة الافتراضية
مفتاح واجهة برمجة التطبيقات	صواب	سلسلة	مفتاح سر المستخدم
ApiKeyName		سلسلة	اسم عنوان Uri الذي يحتوي على قيمة ApiKey	`Authorization`
ApiKeyIdentifier		سلسلة	قيمة السلسلة لإبقاء الرمز المميز مسبقا	`token`
IsApiKeyInPostPayload		boolean	إرسال البيانات السرية في نص 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

يدعم النظام الأساسي للموصل بدون تعليمات برمجية منح رمز التخويل 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`
TokenEndpoint	صواب	السلسلة‬	عنوان URL لتبادل التعليمات البرمجية برمز مميز صالح في `authorization_code` المنحة أو معرف العميل والسر مع رمز مميز صالح في `client_credentials` المنحة.
TokenEndpointHeaders		‏‏الكائن	كائن قيمة مفتاح اختياري لإرسال رؤوس مخصصة إلى خادم الرمز المميز
TokenEndpointQueryParameters		‏‏الكائن	كائن قيمة مفتاح اختياري لإرسال معلمات استعلام مخصصة إلى خادم الرمز المميز
AuthorizationEndpoint	صواب	السلسلة‬	URL لموافقة المستخدم على `authorization_code` التدفق
AuthorizationEndpointHeaders		‏‏الكائن	كائن قيمة مفتاح اختياري لإرسال رؤوس مخصصة إلى خادم المصادقة
AuthorizationEndpointQueryParameters		‏‏الكائن	زوج قيمة مفتاح اختياري مستخدم في طلب تدفق رمز التخويل 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 المميز (JWT)

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

تكوين الطلب

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

الحقل	المطلوب	نوع	‏‏الوصف
نقطة نهاية Api	صواب	السلسلة‬	عنوان URL للخادم البعيد. يحدد نقطة النهاية لسحب البيانات منها.
RateLimitQPS		رقم صحيح	يحدد عدد الاستدعاءات أو الاستعلامات المسموح بها في ثانية واحدة.
QueryWindowInMin		رقم صحيح	تعريف نافذة الاستعلام المتوفرة في دقائق. الحد الأدنى هو دقيقة واحدة. الوقت الافتراضي هو 5 دقائق.
HttpMethod		السلسلة‬	تعريف أسلوب API: `GET`(افتراضي) أو `POST`
تنسيق وقت الاستعلام		السلسلة‬	يحدد تنسيق التاريخ والوقت الذي تتوقعه نقطة النهاية (الخادم البعيد). يستخدم CCP التاريخ والوقت الحاليين أينما يتم استخدام هذا المتغير. القيم المحتملة هي الثوابت: `UnixTimestamp`، `UnixTimestampInMills` أو أي تمثيل صالح آخر لوقت التاريخ، على سبيل المثال: `yyyy-MM-dd`، `MM/dd/yyyy HH:mm:ss` الافتراضي هو ISO 8601 UTC
إعادة المحاولة		عدد صحيح (1...6)	`1` `6` تعريف لإعادة المحاولة المسموح لها بالتعافي من الفشل. القيمة الافتراضية هي `3`.
المهلةInSeconds		عدد صحيح (1...180)	يحدد مهلة الطلب، بالثواني. القيمة الافتراضية هي `20`
IsPostPayloadJson		Boolean	يحدد ما إذا كانت حمولة POST بتنسيق JSON. القيمة الافتراضية هي `false`
رؤوس		‏‏الكائن	أزواج القيمة الرئيسية التي تحدد عناوين الطلب.
QueryParameters		‏‏الكائن	أزواج القيمة الرئيسية التي تحدد معلمات استعلام الطلب.
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`	yes	yes
`_QueryWindowEndTime`	yes	yes
`_APIKeyName`	no	yes
`_APIKey`	no	yes

مثال 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}

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

إشعار

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

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

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

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

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

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

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

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

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

تكوين LinkHeader أو PersistentLinkHeader

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

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

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

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

إشعار

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

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

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

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

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

تكوين NextPageUrl

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

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

مثال:

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 يستخدم ترقيم الصفحات رمزا مميزا يستمر من جانب الخادم. يتذكر الخادم الرمز المميز الأخير الذي قام العميل باسترداده ويوفر الرمز المميز التالي في الطلبات اللاحقة. يستمر العميل من حيث توقف حتى إذا قام بإجراء طلبات جديدة لاحقا.

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

أمثلة:

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

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

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

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

الحقل	المطلوب	نوع	‏‏الوصف
PageSize	خطأ	رقم صحيح	عدد الأحداث لكل صفحة
PageSizeParameterName	خطأ	السلسلة‬	اسم معلمة الاستعلام لحجم الصفحة
OffsetParaName	خطأ	السلسلة‬	اسم معلمة استعلام الطلب التالي. يحسب CCP قيمة الإزاحة لكل طلب، (جميع الأحداث التي تم استيعابها + 1)

مثال:

Paging: {
   
       "pagingType": "Offset", 
        "offsetParaName": "offset" 
 }

تكوين DCR

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

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

فيما يلي مثال على جميع مكونات موصل بيانات CCP 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,
         "queryWindowInMin": 5,
         "httpMethod": "GET",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader"
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}

مشاركة عبر

مرجع موصل بيانات RestApiPoller للنظام الأساسي للموصل بدون تعليمات برمجية

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

معلمات URI

نص الطلب

RestApiPoller

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

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

APIKey

OAuth2

Jwt

تكوين الطلب

مثال StartTimeAttributeName

مثال QueryTimeIntervalAttributeName

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

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

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

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

تكوين LinkHeader أو PersistentLinkHeader

تكوين NextPageUrl

تكوين NextPageToken أو PersistentToken

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

تكوين DCR

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

الملاحظات

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