Kodsuz Bağlayıcı Çerçevesi için RestApiPoller veri bağlayıcısı başvurusu

Bu makaleyi veri bağlayıcıları belgeleri RestApiPoller ek olarak kullanarak Kodsuz Bağlayıcı Çerçevesi (CCF) ile bir veri bağlayıcısı oluşturabilirsiniz.

Her veri bağlayıcısı, Microsoft Sentinel veri bağlayıcısının belirli bir bağlantısını temsil eder. Bir veri bağlayıcısı, farklı uç noktalardan veri getiren birden çok bağlantıya sahip olabilir. Bu makaleyle oluşturduğunuz JSON yapılandırmasını kullanarak CCF veri bağlayıcısı için dağıtım şablonunu tamamlayabilirsiniz.

Daha fazla bilgi için bkz. Microsoft Sentinel için kodsuz bağlayıcı oluşturma.

Veri bağlayıcıları oluşturma veya güncelleştirme

REST API belgelerindeki veya işlemlerine başvurarak create en son kararlı veya update önizleme API sürümünü bulun. ve işlemleri arasındaki create fark, değerin gerekli update olmasıdırupdate.etag

PUT Yöntem:

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

URI parametreleri

En son API sürümü hakkında daha fazla bilgi için bkz . Veri bağlayıcıları: URI parametrelerini oluşturma veya güncelleştirme.

Name	Açıklama
dataConnectorId	Veri bağlayıcısı kimliği. name parametreyle aynı olan benzersiz bir ad olmalıdır.
resourceGroupName	Büyük/küçük harfe duyarlı değil, kaynak grubunun adı.
subscriptionId	Hedef aboneliğin kimliği.
workspaceName	Çalışma alanının adı , kimliği değil. Regex deseni şeklindedir ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$.
api-version	Bu işlem için kullanılacak API sürümü.

İstek gövdesi

CCF RestApiPoller veri bağlayıcısı için istek gövdesi aşağıdaki yapıya sahiptir:

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

RestApiPoller

RestApiPoller veri kaynağınız için disk belleği, yetkilendirme ve istek/yanıt yüklerini özelleştirmek için kullanabileceğiniz bir API poller CCF veri bağlayıcısıdır.

Name	Gerekli	Tür	Açıklama
name	True	Dize	URI parametresiyle eşleşen bağlantının benzersiz adı.
kind	True	Dize	Değer kind . Bu alan olarak RestApiPollerayarlanmalıdır.
etag		GUID	Değer etag . Yeni bağlayıcı oluşturma için bu alan boş bırakılmalıdır. Güncelleştirme işlemleri için mevcut etag bağlayıcıyla etag (GUID) eşleşmesi gerekir.
properties.connectorDefinitionName		Dize	Veri bağlayıcısının DataConnectorDefinition kullanıcı arabirimi yapılandırmasını tanımlayan kaynağın adı. Daha fazla bilgi için Veri bağlayıcısı tanımı'na gidin.
properties.auth	True	İç İçe JSON	Verileri yoklama için kimlik doğrulama özellikleri. Daha fazla bilgi için Kimlik doğrulama yapılandırması'na gidin.
properties.request	True	İç İçe JSON	API uç noktası gibi verilerin yoklanması için istek yükü. Daha fazla bilgi için Yapılandırma isteme bölümüne gidin.
properties. response	True	İç İçe JSON	Api' nin verileri yokladığında döndürdüğü yanıt nesnesi ve iç içe ileti. Daha fazla bilgi için Yanıt yapılandırması'na gidin.
properties.paging		İç İçe JSON	Verileri yoklarken sayfalandırma yükü. Daha fazla bilgi için Sayfalama yapılandırması'na gidin.
properties.dcrConfig		İç İçe JSON	Veriler bir veri toplama kuralına (DCR) gönderildiğinde gerekli parametreler. Daha fazla bilgi için DCR yapılandırması'na gidin.

Kimlik doğrulama yapılandırması

CCF aşağıdaki kimlik doğrulama türlerini destekler:

• Basic
• API anahtarı
• OAuth2
• JWT

Not

CCF OAuth2 uygulaması istemci sertifikası kimlik bilgilerini desteklemez.

En iyi yöntem olarak, kimlik bilgilerini sabit kodlamak yerine kimlik doğrulama bölümündeki parametreleri kullanın. Daha fazla bilgi için bkz . Gizli girişin güvenliğini sağlama.

Parametreleri de kullanan dağıtım şablonunu oluşturmak için, ek bir başlangıç [ile bu bölümdeki parametrelerden kaçış yapmanız gerekir. Bu adım, parametrelerin bağlayıcıyla kullanıcı etkileşimini temel alan bir değer atamasına olanak tanır. Daha fazla bilgi için bkz . Şablon ifadeleri kaçış karakterleri.

Kimlik bilgilerinin kullanıcı arabiriminden girilebilmesini sağlamak için bölümünde connectorUIConfig istenen parametreleri instructionsgirmeniz gerekir. Daha fazla bilgi için bkz. Kodsuz Bağlayıcı Çerçevesi için veri bağlayıcısı tanımları başvurusu.

Temel kimlik doğrulaması

Alan	Gerekli	Tür
UserName	True	Dize
Password	True	Dize

aşağıda, içinde tanımlanan parametreleri kullanan temel kimlik doğrulaması örneği verilmiştir connectorUIconfig:

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

API anahtarı

Alan	Gerekli	Tür	Açıklama	Varsayılan değer
ApiKey	True	Dize	Kullanıcı gizli anahtarı.
ApiKeyName		Dize	Değeri içeren URI üst bilgisinin ApiKey adı.	Authorization
ApiKeyIdentifier		Dize	Belirtecin başına eklemek için dize değeri.	token
IsApiKeyInPostPayload		Boole	Gizli anahtarın üst bilgi yerine gövdede POST gönderilip gönderilmeyeceğini belirleyen değer.	false

APIKey kimlik doğrulama örnekleri:

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

Bu örneğin sonucu, aşağıdaki üst bilgide gönderilen kullanıcı girişinden tanımlanan gizli dizidir: X-MyApp-Auth-Header. Bearer apikey

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

Bu örnek, varsayılan değerleri kullanır ve şu üst bilgiyle sonuçlanır: Authorization: token 123123123.

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

ApiKeyName açıkça olarak ""olarak ayarlandığından, sonuç şu üst bilgidir: Authorization: 123123123.

OAuth2

Kodsuz Bağlayıcı Çerçevesi, OAuth 2.0 yetkilendirme kodu verme ve istemci kimlik bilgilerini destekler. Yetkilendirme Kodu verme türü, gizli ve genel istemciler tarafından erişim belirteci için yetkilendirme kodu değişimi yapmak için kullanılır.

Kullanıcı yeniden yönlendirme URL'si aracılığıyla istemciye döndükten sonra, uygulama URL'den yetkilendirme kodunu alır ve erişim belirteci istemek için kullanır.

Alan	Gerekli	Tür	Açıklama
ClientId	True.	Dize	İstemci kimliği.
ClientSecret	True.	Dize	İstemci gizli dizisi.
AuthorizationCode	Değer olduğunda grantType true değeridir authorization_code.	Dize	Verme türü ise authorization_code, bu alan değeri kimlik doğrulama sunucusunun döndürdüğünü yetkilendirme kodudur.
Scope	Verme türü için authorization_code true. Verme türü için client_credentials isteğe bağlı.	Dize	Kullanıcı onayı için boşlukla ayrılmış kapsam listesi. Daha fazla bilgi için bkz . OAuth2 kapsamları ve izinleri.
RedirectUri	Değer olduğunda grantType true değeridir authorization_code.	Dize	Yeniden yönlendirme URL'si olmalıdır https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights.
GrantType	True.	Dize	Verme türü. veya authorization_codeolabilirclient_credentials.
TokenEndpoint	True.	Dize	Vermede geçerli bir belirteçle kod değiştirme URL'si veya vermede authorization_code geçerli bir belirteç client_credentials içeren bir istemci kimliği ve gizli dizi.
TokenEndpointHeaders		Nesne	Belirteç sunucusuna özel üst bilgiler göndermek için isteğe bağlı bir anahtar/değer nesnesi.
TokenEndpointQueryParameters		Nesne	Belirteç sunucusuna özel sorgu parametreleri göndermek için isteğe bağlı bir anahtar/değer nesnesi.
AuthorizationEndpoint	True.	Dize	Akış için kullanıcı onayı URL'si authorization_code .
AuthorizationEndpointHeaders		Nesne	Kimlik doğrulama sunucusuna özel üst bilgiler göndermek için isteğe bağlı bir anahtar/değer nesnesi.
AuthorizationEndpointQueryParameters		Nesne	OAuth2 yetkilendirme kodu akış isteğinde kullanılan isteğe bağlı anahtar/değer çifti.

Kullanıcının izinleri adına veri getirmek için kimlik doğrulama kodu akışını kullanabilirsiniz. Uygulama izinlerine sahip verileri getirmek için istemci kimlik bilgilerini kullanabilirsiniz. Veri sunucusu uygulamaya erişim izni verir. İstemci kimlik bilgileri akışında kullanıcı olmadığından, yetkilendirme uç noktası gerekmez, yalnızca belirteç uç noktası gerekir.

İşte OAuth2 authorization_code verme türüne bir örnek:

"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"
}

İşte OAuth2 client_credentials verme türüne bir örnek:

"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 Belirteci (JWT) kimlik doğrulaması, belirteçlerin kullanıcı adı ve parola kimlik bilgileri aracılığıyla alınıp API istekleri için kullanılmasını destekler.

Temel örnek

"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 gövdesindeki kimlik bilgileri (varsayılan)

"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"
}

Üst bilgilerdeki kimlik bilgileri (temel kimlik doğrulaması)

"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
}

Üst bilgilerdeki kimlik bilgileri (kullanıcı belirteci)

"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"
}

Şu kimlik doğrulama akışını izleyin:

1. JWT belirtecini almak için adresine kimlik bilgileri TokenEndpoint gönderin; ve userNamepassword kullanılırkenIsCredentialsInHeaders, istekte kimlik bilgilerinin nereye yerleştirileceğini belirlemek için kullanılır.

   • if IsCredentialsInHeaders: true: ile username:passwordtemel bir kimlik doğrulama üst bilgisi gönderir.
   • If IsCredentialsInHeaders: false: Kimlik bilgilerini bir POST gövdeye gönderir.

2. Yanıt üst bilgisinden veya kullanarak JwtTokenJsonPath belirteci ayıklayın.

3. JWT belirteçleri için Yetkilendirme üst bilgisi bir sabittir ve her zaman "Yetkilendirme" olacaktır.

Alan	Gerekli	Tür	Açıklama
type	True	Dize	Türü. Olmalıdır JwtToken
userName	True (kullanılmıyorsa userToken )	Nesne	Kimlik bilgisi için anahtar/değer çifti userName . Üst bilgi isteğinde ve gönderiliyorsauserName, özelliğini kullanıcı adıyla belirtinpassword.value Gövde isteğinde ve userName gönderiliyorsa password ve KeybelirtinValue.
password	True (kullanılmıyorsa userToken )	Nesne	Parola kimlik bilgileri için anahtar/değer çifti. ve üst bilgi isteğinde gönderilirseuserName, özelliğini ile passwordbelirtinvalue.userName Gövde isteğinde ve userName gönderiliyorsa password ve KeybelirtinValue.
userToken	True (kullanılmıyorsa userName )	Dize	Kimlik doğrulaması için sistem belirtecini almak için istemci tarafından oluşturulan kullanıcı belirteci.
UserTokenPrepend	False	Dize	Belirtecin önüne metin eklenip eklenmeyeceğini gösteren değer. Varsayılan: Bearer.
NoAccessTokenPrepend	False	Boole	Belirtecin hiçbir şey eklememesi gerektiğini gösteren erişim bayrağı.
TokenEndpointHttpMethod	False	Dize	Belirteç uç noktası için HTTP yöntemi. Veya GetolabilirPost. Varsayılan değerdir Post.
TokenEndpoint	True	Dize	JWT belirtecini almak için kullanılan URL uç noktası.
IsCredentialsInHeaders		Boole	Kimlik bilgilerinin temel kimlik doğrulama üst bilgisi () olarak mı (true) yoksa gövde POST (false olarak mı gönderildiğini) belirten değer kullanılırken userTokenyoksayılır. Varsayılan değerdir false.
IsJsonRequest		Boole	İsteğin JSON (üst bilgi) ile form kodlamalı (üst Content-Type = application/jsonbilgi Content-Type = application/x-www-form-urlencoded) içinde gönderilip gönderilmeydiğini gösteren değerdir. Varsayılan değerdir false.
JwtTokenJsonPath		Dize	Yanıtın belirtecini JSONPath ayıklamak için kullanılacak değeri gösteren değer. Örneğin: $.access_token.
JwtTokenInResponseHeader		Boole	Belirtecin yanıt üst bilgisinden gövdeye göre ayıklanıp ayıklanmayacağını gösteren değer. Varsayılan değerdir false.
JwtTokenHeaderName.		Dize	Belirteç yanıt üst bilgisinde olduğunda üst bilgi adını gösteren değer. Varsayılan değerdir Authorization.
JwtTokenIdentifier		Dize	Ön ekli belirteç dizesinden JWT'yi ayıklamak için kullanılan tanımlayıcı.
QueryParameters		Nesne	İstek belirteç uç noktasına gönderilirken eklenecek özel sorgu parametreleri.
Headers		Nesne	İstek belirteç uç noktasına gönderilirken eklenecek özel üst bilgiler.
RequestTimeoutInSeconds		Tamsayı	saniyeler içinde istek zaman aşımı. Varsayılan değer, en yüksek değeri olan değeridir100300.

Not

Sınırlamalar

• Belirteç alımı için kullanıcı adı ve parola kimlik doğrulaması gerektirir
• API anahtar tabanlı belirteç isteklerini desteklemez
• Özel üst bilgi kimlik doğrulamasını desteklemez (kullanıcı adı ve parola olmadan)

İstek yapılandırması

İstek bölümü, CCF veri bağlayıcısının veri kaynağınıza nasıl istek gönderdiğini tanımlar (örneğin, API uç noktası ve bu uç noktayı yoklama sıklıkları).

Alan	Gerekli	Tür	Açıklama
ApiEndpoint	True.	Dize	Bu alan, uzak sunucunun URL'sini belirler ve verilerin çekildiği uç noktayı tanımlar.
RateLimitQPS		Tamsayı	Bu alan, ilk istek için saniye içinde izin verilen çağrı veya sorgu sayısını tanımlar. Sayfalandırılmış istekler için geçerli değildir. Sayfalandırmayı kısıtlamak için öğesini de ayarlayın PaginatedCallsPerSecond.
PaginatedCallsPerSecond		Çift (0...1000)	Bu alan, RESTful API'sine yönelik sayfalandırılmış istekler için saniye başına izin verilen çağrı sayısını tanımlar. Her sayfalandırılmış API çağrısı arasında milisaniyelik bir gecikmeye (1000 / paginatedCallsPerSecond) neden olur. Bu azaltma yalnızca sayfalandırma istekleri için geçerlidir ve ilk istek hızını denetleyen öğesinden RateLimitQPSayrıdır. Genellikle, bu değer RateLimitQPS tüm istekler genelinde veri kaynağının hız sınırına göre ayarlanır. 0 değer, sayfalandırma azaltma uygulanmadığını gösterir.
RateLimitConfig		Nesne	Bu alan, RESTful API'sinin hız sınırı yapılandırmasını tanımlar. Daha fazla bilgi için örnek bölümüne RateLimitConfiggidin.
QueryWindowInMin		Tamsayı	Bu alan, kullanılabilir sorgu penceresini dakika cinsinden tanımlar. En az 1 dakikadır. Varsayılan değer 5 dakikadır.
HttpMethod		Dize	Bu alan API yöntemini tanımlar: GET(varsayılan) veya POST.
QueryTimeFormat		Dize	Bu alan, uç noktanın (uzak sunucu) beklediği tarih ve saat biçimini tanımlar. CCF, bu değişkenin kullanıldığı her yerde geçerli tarih ve saati kullanır. Olası değerler sabitlerdir: UnixTimestamp, UnixTimestampInMillsveya tarih ve saatin diğer geçerli gösterimleri. Örneğin: yyyy-MM-dd, MM/dd/yyyy HH:mm:ss. Varsayılan değerdir ISO 8601 UTC.
RetryCount		Tamsayı (1...6)	Bu alan, yeniden deneme değerlerinin 16 bir hatadan kurtarılmalarına izin verildiğini tanımlar. Varsayılan değer şeklindedir 3.
TimeoutInSeconds		Tamsayı (1...300)	Bu alan, istek zaman aşımını saniyeler içinde tanımlar. Varsayılan değer şeklindedir 20.
IsPostPayloadJson		Boole	Bu alan yükün POST JSON biçiminde olup olmadığını belirler. Varsayılan değer şeklindedir false.
Headers		Nesne	Bu alan, istek üst bilgilerini tanımlayan anahtar/değer çiftlerini içerir.
QueryParameters		Nesne	Bu alan, istek sorgusu parametrelerini tanımlayan anahtar/değer çiftlerini içerir.
StartTimeAttributeName	EndTimeAttributeName Değer ayarlandığında true.	Dize	Bu alan, sorgu başlangıç saati için sorgu parametresi adını tanımlar. Daha fazla bilgi için örnek bölümüne StartTimeAttributeNamegidin.
EndTimeAttributeName	StartTimeAttributeName Ayarlandığında true.	Dize	Bu alan, sorgu bitiş saati için sorgu parametresi adını tanımlar.
QueryTimeIntervalAttributeName		Dize	Bu alan, uç nokta bir zaman çerçevesindeki verileri sorgulamak için özelleştirilmiş bir biçim gerektiriyorsa kullanılır. ve parametreleriyle QueryTimeIntervalPrependQueryTimeIntervalDelimiter bu özelliği kullanın. Daha fazla bilgi için örnek bölümüne QueryTimeIntervalAttributeNamegidin.
QueryTimeIntervalPrepend	QueryTimeIntervalAttributeName Ayarlandığında true.	Dize	Başvurusu QueryTimeIntervalAttributeName.
QueryTimeIntervalDelimiter	QueryTimeIntervalAttributeName Ayarlandığında true.	Dize	Başvurusu QueryTimeIntervalAttributeName.
QueryParametersTemplate		Dize	Bu alan, gelişmiş senaryolarda parametreleri geçirirken kullanılacak sorgu şablonuna başvurur. Örneğin: "queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}".
InitialCheckpointTimeUtc		DateTime (UTC)	Depolanmış bir denetim noktası olmadığında ilk yoklama için sorgu başlangıç zamanını belirtir. İlk başarılı yoklamadan sonra bir denetim noktası kalıcı hale geldikten sonra bu değer yoksayılır. Bu ayar yalnızca bağlayıcının istek yapılandırması karşılık gelen bir bitiş zamanı parametresi olmadan bir başlangıç zamanı sorgu parametresi (veya startTimeAttributeName değiştirme belirteci gibi{_QueryWindowStartTime}) tanımladığında geçerlilik kazanır. Yalnızca sayfalandırma imleçlerine veya belirteçlere dayanan bağlayıcılar üzerinde hiçbir etkisi yoktur. Biçim: ISO 8601 UTC datetime (örneğin, 2024-01-15T00:00:00Z).

API karmaşık parametreler gerektirdiğinde veya queryParameterskullanınqueryParametersTemplate. Bu komutlar bazı yerleşik değişkenleri içerir.

Yerleşik değişken	Kullanım için: queryParameters	Kullanım için: queryParametersTemplate
_QueryWindowStartTime	Evet	Evet
_QueryWindowEndTime	Evet	Evet
_APIKeyName	Hayır	Evet
_APIKey	Hayır	Evet

StartTimeAttributeName örneği

Şu örneği göz önünde bulundurun:

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

Uzak sunucuya gönderilen sorgu: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

QueryTimeIntervalAttributeName örneği

Şu örneği göz önünde bulundurun:

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

Uzak sunucuya gönderilen sorgu: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

RateLimitConfig örneği

Şu örneği göz önünde bulundurun:

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
  }
}

Yanıt hız sınırı üst bilgilerini içerdiğinde bağlayıcı, istek hızını ayarlamak için bu bilgileri kullanabilir.

Veri kaynağı API'si olarak Microsoft Graph kullanan istek örnekleri

Bu örnek, iletileri filtre sorgu parametresiyle sorgular. Daha fazla bilgi için bkz. Microsoft Graph API sorgu parametreleri.

"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 "
}

Önceki örnek adresine GETbir https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000 istek gönderir. Zaman damgası her queryWindowInMin zaman için güncelleştirilir.

Bu örnekle aynı sonuçları elde edebilirsiniz:

"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}"
  }
}

Veri kaynağının iki sorgu parametresi beklediği durumlar için başka bir seçenek vardır (biri başlangıç saati, biri bitiş saati için).

Örneğin:

"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",
}

Bu seçenek adresine GETbir https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000 istek gönderir.

Karmaşık sorgular için kullanın QueryParametersTemplate. Bu örnek, gövdesindeki parametrelerle bir POST istek gönderir:

"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}))\"}"
}

Yanıt yapılandırması

Aşağıdaki parametreleri kullanarak veri bağlayıcınızın yanıtları nasıl işlediğini tanımlayın:

Alan	Gerekli	Tür	Açıklama
EventsJsonPaths	True	Dizelerin listesi	Yanıt JSON'unda iletinin yolunu tanımlar. JSON yol ifadesi, JSON yapısında bir öğenin veya öğe kümesinin yolunu belirtir.
SuccessStatusJsonPath		Dize	Yanıt JSON'unda başarı iletisinin yolunu tanımlar. Bu parametre tanımlandığında parametresi de SuccessStatusValue tanımlanmalıdır.
SuccessStatusValue		Dize	Yanıt JSON'sindeki başarı iletisi değerinin yolunu tanımlar.
IsGzipCompressed		Boole	Yanıtın bir GZIP dosyasında sıkıştırılıp sıkıştırılmayacağını belirler.
format	True	Dize	Biçimin json, csvveya xmlolup olmadığını belirler.
CompressionAlgo		Dize	Veya multi-gzipsıkıştırma algoritmasını deflate tanımlar. GZIP sıkıştırma algoritması için, bu parametre için bir değer ayarlamak yerine olarak yapılandırın IsGzipCompressedTrue .
CsvDelimiter		Dize	Yanıt biçimi CSV ise ve varsayılan CSV sınırlayıcısını değiştirmek istiyorsanız başvurur ",".
HasCsvBoundary		Boole	CSV verilerinin bir sınırı olup olmadığını gösterir.
HasCsvHeader		Boole	CSV verilerinin üst bilgisi olup olmadığını gösterir. Varsayılan değerdir True.
CsvEscape		Dize	Alan sınırı için bir kaçış karakteri tanımlar. Varsayılan değer şudur: " Örneğin, üst bilgileri olan bir CSV ve gibi boşluklar id,name,avg içeren bir veri satırı alan sınırı gerektirir1,"my name",5.5."
ConvertChildPropertiesToArray		Boole	Her özelliğin veri içerdiği olayların listesi yerine uzak sunucunun bir nesne döndürdüğü özel bir duruma başvurur.

Not

CSV biçim türü belirtim tarafından RFC4180 ayrıştırılır.

Yanıt yapılandırma örnekleri

JSON biçiminde bir sunucu yanıtı beklenir. Yanıtta istenen veriler özellik değerinde yer alır. Yanıt özelliği durumu , verilerin yalnızca değeri successise alınamadığını gösterir.

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

Bu örnekte beklenen yanıt, üst bilgi içermeyen bir CSV için hazırlanır.

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

Disk belleği yapılandırması

Veri kaynağı yanıt yükünün tamamını aynı anda gönderemiyorsa CCF veri bağlayıcısının yanıt sayfalarındaki verilerin bölümlerini nasıl alacağını bilmesi gerekir. Aralarından seçim yapabileceğiniz disk belleği türleri şunlardır:

Disk belleği türü	Karar faktörü
LinkHeader PersistentLinkHeader NextPageUrl	API yanıtının sonraki ve önceki sayfalara bağlantıları var mı?
NextPageToken PersistentToken	API yanıtının sonraki ve önceki sayfalar için bir belirteci veya imleci var mı?
Offset	API yanıtı, disk belleği sırasında atlanan nesne sayısı için bir parametreyi destekliyor mu?
CountBasedPaging	API yanıtı, döndürülecek nesne sayısı için bir parametreyi destekliyor mu?

LinkHeader veya PersistentLinkHeader'ı yapılandırma

En yaygın disk belleği türü, bir sunucu veri kaynağı API'sinin sonraki ve önceki veri sayfalarına URL'ler sağlamasıdır. Bağlantı Üst Bilgisi belirtimi hakkında daha fazla bilgi için bkzRFC 5988. .

LinkHeader disk belleği, API yanıtının şunları içerdiği anlamına gelir:

• Link HTTP yanıt üst bilgisi.
• Yanıt gövdesinden bağlantıyı almak için bir JSON yolu.

PersistentLinkHeader-type disk belleği, bağlantı üst bilgisinin arka uç depolama alanında kalıcı olması dışında ile aynı özelliklere LinkHeadersahiptir. Bu seçenek, sorgu pencerelerinin disk belleği bağlantılarını etkinleştirir.

Örneğin, bazı API'ler sorgu başlangıç saatlerini veya bitiş saatlerini desteklemez. Bunun yerine, bir sunucu tarafı imlecini destekler. Sunucu tarafı imlecini hatırlamak için kalıcı sayfa türlerini kullanabilirsiniz. Daha fazla bilgi için bkz. İmleç nedir?.

Not

Sunucu tarafındaki PersistentLinkHeader yarış koşullarını önlemek için bağlayıcı için yalnızca bir sorgu ile çalıştırılabilir. Bu sorun gecikme süresini etkileyebilir.

Alan	Gerekli	Tür	Açıklama
LinkHeaderTokenJsonPath	False	Dize	Yanıt gövdesindeki değerin nereden alınacağı belirtmek için bu özelliği kullanın. Örneğin, veri kaynağı aşağıdaki JSON değerini { nextPage: "foo", value: [{data}]}döndürürse, LinkHeaderTokenJsonPath değeri olur $.nextPage.
PageSize	False	Tamsayı	Sayfa başına olay sayısını belirlemek için bu özelliği kullanın.
PageSizeParameterName	False	Dize	Sayfa boyutunu belirtmek için bu sorgu parametresi adını kullanın.
PagingInfoPlacement	False	Dize	Disk belleği bilgilerinin nasıl dolduruldığını belirlemek için bu özelliği kullanın. veya QueryStringkabul ederRequestBody.
PagingQueryParamOnly	False	Boole	Sorgu parametrelerini belirtmek için bu özelliği kullanın. true olarak ayarlanırsa, disk belleği sorgu parametreleri dışında diğer tüm sorgu parametrelerini atlar.

İşte birkaç örnek:

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

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

NextPageUrl'i yapılandırma

NextPageUrl-type disk belleği, API yanıtının yanıt gövdesinde öğesine LinkHeaderbenzer karmaşık bir bağlantı içerdiği, ancak URL'nin üst bilgi yerine yanıt gövdesine dahil olduğu anlamına gelir.

Alan	Gerekli	Tür	Açıklama
PageSize	False	Tamsayı	Sayfa başına olay sayısı.
PageSizeParameterName	False	Dize	Sayfa boyutu için sorgu parametresi adı.
NextPageUrl	False	Dize	Yalnızca bağlayıcı Coralogix API'sine yönelikse kullanılan alan.
NextPageUrlQueryParameters	False	Nesne	Sonraki sayfa için her isteğe özel sorgu parametresi ekleyen anahtar/değer çiftleri.
NextPageParaName	False	Dize	İstekteki sonraki sayfa adı.
HasNextFlagJsonPath	False	Dize	flag özniteliğinin HasNextPage yolu.
NextPageRequestHeader	False	Dize	İstekteki sonraki sayfa üst bilgisi adı.
NextPageUrlQueryParametersTemplate	False	Dize	Yalnızca bağlayıcı Coralogix API'sine yönelikse kullanılan alan.
PagingInfoPlacement	False	Dize	Disk belleği bilgilerinin nasıl doldurulduğunu belirleyen alan. veya QueryStringkabul ederRequestBody.
PagingQueryParamOnly	False	Boole	Sorgu parametrelerini belirleyen alan. true olarak ayarlanırsa, disk belleği sorgu parametreleri dışında diğer tüm sorgu parametrelerini atlar.

Örneğin:

"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 veya PersistentToken'ı yapılandırma

NextPageToken-type sayfalandırma, geçerli sayfanın durumunu temsil eden bir belirteç (karma veya imleç) kullanır. Belirteç API yanıtına eklenir ve istemci sonraki sayfayı getirmek için bunu sonraki isteğe ekler. Bu yöntem genellikle sunucunun istekler arasındaki tam durumu koruması gerektiğinde kullanılır.

PersistentToken sayfalandırma, sunucu tarafını kalıcı hale getiren bir belirteç kullanır. Sunucu, istemcinin son alınan belirtecini hatırlar ve sonraki isteklerde sonraki belirteci sağlar. İstemci, daha sonra yeni isteklerde bulunsa bile kaldığı yerden devam eder.

Alan	Gerekli	Tür	Açıklama
PageSize	False	Tamsayı	Sayfa başına olay sayısı.
PageSizeParameterName	False	Dize	Sayfa boyutu için sorgu parametresi adı.
NextPageTokenJsonPath	False	Dize	Yanıt gövdesindeki sonraki sayfa belirtecinin JSON yolu.
NextPageTokenResponseHeader	False	Dize	Boşsa NextPageTokenJsonPath , sonraki sayfa için bu üst bilgi adındaki belirteci kullanacağınızı belirten alan.
NextPageParaName	False	Dize	İstekteki sonraki sayfa adını belirleyen alan.
HasNextFlagJsonPath	False	Dize	Yanıtta daha fazla sayfa bırakılıp bırakılmadığını belirlerken bayrak HasNextPage özniteliğinin yolunu tanımlayan alan.
NextPageRequestHeader	False	Dize	İstekteki sonraki sayfa üst bilgisi adını belirleyen alan.
PagingInfoPlacement	False	Dize	Disk belleği bilgilerinin nasıl doldurulduğunu belirleyen alan. veya QueryStringkabul ederRequestBody.
PagingQueryParamOnly	False	Boole	Sorgu parametrelerini belirleyen alan. true olarak ayarlanırsa, disk belleği sorgu parametreleri dışında diğer tüm sorgu parametrelerini atlar.

Örnekler:

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

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

Uzaklığı Yapılandır

Offset-type sayfalandırma, atlanması gereken sayfa sayısını ve istekteki sayfa başına alınacak olay sayısı sınırını belirtir. İstemciler veri kümesinden belirli bir öğe aralığını getirir.

Alan	Gerekli	Tür	Açıklama
PageSize	False	Tamsayı	Sayfa başına olay sayısı.
PageSizeParameterName	False	Dize	Sayfa boyutu için sorgu parametresi adı.
OffsetParaName	False	Dize	Sonraki istek sorgusu parametre adı. CCF, her istek için uzaklık değerini hesaplar (alınan tüm olaylar + 1).
PagingInfoPlacement	False	Dize	Disk belleği bilgilerinin nasıl doldurulduğunu belirleyen alan. veya QueryStringkabul ederRequestBody.
PagingQueryParamOnly	False	Boole	Sorgu parametrelerini belirleyen alan. true olarak ayarlanırsa, disk belleği sorgu parametreleri dışında diğer tüm sorgu parametrelerini atlar.

Örneğin:

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

CountBasedPaging'ı yapılandırma

CountBasedPaging-type sayfalandırma, istemcinin yanıtta döndürülecek öğe sayısını belirtmesine olanak tanır. Bu özellik, yanıt yükünün bir parçası olarak bir count parametresine dayalı olarak sayfalandırmayı destekleyen API'ler için kullanışlıdır.

Alan	Gerekli	Tür	Açıklama
pageNumberParaName	True	Dize	HTTP isteğindeki sayfa numarasının parametre adı.
PageSize	False	Tamsayı	Sayfa başına olay sayısı.
ZeroBasedIndexing	False	Boole	Sayın sıfır tabanlı olduğunu belirten bayrak.
HasNextFlagJsonPath	False	Dize	HTTP yanıt yükündeki bayrağın JSON yolu, daha fazla sayfa olduğunu gösterir.
TotalResultsJsonPath	False	Dize	HTTP yanıt yükündeki toplam sonuç sayısının JSON yolu.
PageNumberJsonPath	False	Dize	HTTP yanıt yükündeki sayfa numarasının JSON yolu. Sağlanmışsa totalResultsJsonPath gereklidir.
PageCountJsonPath	False	Dize	HTTP yanıt yükündeki sayfa sayısının JSON yolu. Sağlanmışsa totalResultsJsonPath gereklidir.
PagingInfoPlacement	False	Dize	Disk belleği bilgilerinin nasıl doldurulduğunu belirleyen alan. veya QueryStringkabul ederRequestBody.
PagingQueryParamOnly	False	Boole	Sorgu parametrelerini belirleyen alan. true olarak ayarlanırsa, disk belleği sorgu parametreleri dışında diğer tüm sorgu parametrelerini atlar.

Örneğin:

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

DCR yapılandırması

Alan	Gerekli	Tür	Açıklama
DataCollectionEndpoint	True	Dize	Veri toplama uç noktası (DCE). Örneğin: https://example.ingest.monitor.azure.com.
DataCollectionRuleImmutableId	True	Dize	DCR sabit kimliği. DCR oluşturma yanıtını görüntüleyerek veya DCR API'sini kullanarak bu yanıtı bulun.
StreamName	True	Dize	Bu değer, DCR'de tanımlanan değerdir streamDeclaration . Ön ek ile Custom-başlamalıdır.

Örnek CCF veri bağlayıcısı

CCF veri bağlayıcısı JSON'un tüm bileşenlerine bir örnek aşağıda verilmiştir:

{
   "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": ["$"]
      }
   }
}