Azure Data Factory'yi kullanarak REST uç noktasından ve REST uç noktasına veri kopyalama ve dönüştürme

  • Makale

UYGULANANLAR: Azure Data Factory Azure Synapse Analytics

İpucu

Kuruluşlar için hepsi bir arada analiz çözümü olan Microsoft Fabric'te Data Factory'yi deneyin. Microsoft Fabric , veri taşımadan veri bilimine, gerçek zamanlı analize, iş zekasına ve raporlamaya kadar her şeyi kapsar. Yeni bir deneme sürümünü ücretsiz olarak başlatmayı öğrenin!

Bu makale, REST uç noktasından ve REST uç noktasına veri kopyalamak için Azure Data Factory’deki Kopyalama Etkinliğini kullanmayı özetler. Makale, Azure Data Factory'deki Kopyalama Etkinliğine genel bir bakış sunan Kopyalama Etkinliği üzerine oluşturulmuştur.

Bu REST bağlayıcısı, HTTP bağlayıcısı ve Web tablosu bağlayıcısı arasındaki farklar şunlardır:

  • REST bağlayıcısı, RESTful API'lerinden veri kopyalamayı özellikle destekler.
  • HTTP bağlayıcısı, herhangi bir HTTP uç noktasından (örneğin, dosyayı indirmek için) veri almak için geneldir. Bu REST bağlayıcısından önce, REST bağlayıcısı ile karşılaştırıldığında desteklenen ancak daha az işlevsel olan RESTful API'lerinden veri kopyalamak için HTTP bağlayıcısını kullanabilirsiniz.
  • Web tablosu bağlayıcısı, bir HTML web sayfasından tablo içeriğini ayıklar.

Desteklenen özellikler

Bu REST bağlayıcısı aşağıdaki özellikler için desteklenir:

Desteklenen özellikler IR
Kopyalama etkinliği (kaynak/havuz) (1) (2)
Eşleme veri akışı (kaynak/havuz) (1)

(1) Azure tümleştirme çalışma zamanı (2) Şirket içinde barındırılan tümleştirme çalışma zamanı

Kaynak/havuz olarak desteklenen veri depolarının listesi için bkz . Desteklenen veri depoları.

Özellikle, bu genel REST bağlayıcısı şunları destekler:

  • GET veya POST yöntemlerini kullanarak bir REST uç noktasından veri kopyalama ve POST, PUT veya PATCH yöntemlerini kullanarak verileri REST uç noktasına kopyalama.
  • Aşağıdaki kimlik doğrulamalarından birini kullanarak veri kopyalama: Anonim, Temel, Hizmet Sorumlusu, OAuth2 İstemci Kimlik Bilgileri, Sistem Tarafından Atanan Yönetilen Kimlik ve Kullanıcı Tarafından Atanan Yönetilen Kimlik.
  • REST API'lerinde sayfalandırma .
  • Kaynak olarak REST için REST JSON yanıtını olduğu gibi kopyalayın veya şema eşlemesini kullanarak ayrıştırın. Yalnızca JSON'da yanıt yükü desteklenir.

İpucu

Data Factory'de REST bağlayıcısını yapılandırmadan önce veri alma isteğini test etmek için üst bilgi ve gövde gereksinimleri için API belirtimi hakkında bilgi edinin. Doğrulamak için Postman veya web tarayıcısı gibi araçları kullanabilirsiniz.

Önkoşullar

Veri deponuz bir şirket içi ağ, Azure sanal ağı veya Amazon Sanal Özel Bulut içinde bulunuyorsa, şirket içinde barındırılan tümleştirme çalışma zamanını buna bağlanmak için yapılandırmanız gerekir.

Veri deponuz yönetilen bir bulut veri hizmetiyse Azure Integration Runtime'ı kullanabilirsiniz. Erişim, güvenlik duvarı kurallarında onaylanan IP'ler ile sınırlıysa Azure Integration Runtime IP'lerini izin verme listesine ekleyebilirsiniz.

Şirket içinde barındırılan tümleştirme çalışma zamanı yüklemeden ve yapılandırmadan şirket içi ağa erişmek için Azure Data Factory'deki yönetilen sanal ağ tümleştirme çalışma zamanı özelliğini de kullanabilirsiniz.

Data Factory tarafından desteklenen ağ güvenlik mekanizmaları ve seçenekleri hakkında daha fazla bilgi için bkz . Veri erişim stratejileri.

Kullanmaya başlayın

İşlem hattıyla Kopyalama etkinliği gerçekleştirmek için aşağıdaki araçlardan veya SDK'lardan birini kullanabilirsiniz:

Kullanıcı arabirimini kullanarak REST bağlantılı hizmet oluşturma

Azure portalı kullanıcı arabiriminde REST bağlı hizmeti oluşturmak için aşağıdaki adımları kullanın.

  1. Azure Data Factory veya Synapse çalışma alanınızda Yönet sekmesine gidin ve Bağlı Hizmetler'i ve ardından Yeni'yi seçin:

  2. REST araması yapın ve REST bağlayıcısını seçin.

    Select REST connector.

  3. Hizmet ayrıntılarını yapılandırın, bağlantıyı test edin ve yeni bağlı hizmeti oluşturun.

    Configure REST linked service.

Bağlan veya yapılandırma ayrıntıları

Aşağıdaki bölümlerde, REST bağlayıcısına özgü Data Factory varlıklarını tanımlamak için kullanabileceğiniz özelliklerle ilgili ayrıntılar sağlanır.

Bağlı hizmet özellikleri

REST bağlı hizmeti için aşağıdaki özellikler desteklenir:

Özellik Açıklama Gerekli
Tür Tür özelliği RestService olarak ayarlanmalıdır. Yes
url REST hizmetinin temel URL'si. Yes
enableServerCertificateValidation Uç noktaya bağlanırken sunucu tarafı TLS/SSL sertifikasının doğrulanıp doğrulanmayacağı. Hayır
(varsayılan değer true'dur)
authenticationType REST hizmetine bağlanmak için kullanılan kimlik doğrulama türü. İzin verilen değerler Anonim, Temel, AadServicePrincipal, OAuth2ClientCredential ve ManagedServiceIdentity değerleridir. Ayrıca özelliğinde authHeaders kimlik doğrulama üst bilgilerini yapılandırabilirsiniz. Sırasıyla daha fazla özellik ve örnek için aşağıdaki ilgili bölümlere bakın. Yes
authHeaders Kimlik doğrulaması için ek HTTP isteği üst bilgileri.
Örneğin, API anahtarı kimlik doğrulamasını kullanmak için kimlik doğrulama türünü "Anonim" olarak seçebilir ve üst bilgide API anahtarı belirtebilirsiniz.		 Hayır
connectVia Veri deposuna bağlanmak için kullanılacak Integration Runtime. Önkoşullar bölümünden daha fazla bilgi edinin. Belirtilmezse, bu özellik varsayılan Azure Integration Runtime'ı kullanır. Hayır

Farklı kimlik doğrulama türleri için ayrıntılar için ilgili bölümlere bakın.

Temel kimlik doğrulamayı kullanma

authenticationType özelliğini Temel olarak ayarlayın. Önceki bölümde açıklanan genel özelliklere ek olarak aşağıdaki özellikleri belirtin:

Özellik Açıklama Gerekli
userName REST uç noktasına erişmek için kullanılacak kullanıcı adı. Yes
password Kullanıcının parolası ( userName değeri). Data Factory'de güvenli bir şekilde depolamak için bu alanı SecureString türü olarak işaretleyin. Azure Key Vault'ta depolanan bir gizli diziye de başvurabilirsiniz. Yes

Örnek

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

Hizmet Sorumlusu kimlik doğrulamayı kullanma

authenticationType özelliğini AadServicePrincipal olarak ayarlayın. Önceki bölümde açıklanan genel özelliklere ek olarak aşağıdaki özellikleri belirtin:

Özellik Açıklama Gerekli
servicePrincipalId Microsoft Entra uygulamasının istemci kimliğini belirtin. Yes
servicePrincipalKey Microsoft Entra uygulamasının anahtarını belirtin. Data Factory'de güvenli bir şekilde depolamak için bu alanı SecureString olarak işaretleyin veya Azure Key Vault'ta depolanan bir gizli diziye başvurun. Yes
tenant Uygulamanızın bulunduğu kiracı bilgilerini (etki alanı adı veya kiracı kimliği) belirtin. Fareyi Azure portalının sağ üst köşesine getirerek alın. Yes
aadResourceId Yetkilendirme için istediğiniz Microsoft Entra kaynağını belirtin, örneğin, https://management.core.windows.net. Yes
azureCloudType Hizmet Sorumlusu kimlik doğrulaması için Microsoft Entra uygulamanızın kaydedildiği Azure bulut ortamının türünü belirtin.
İzin verilen değerler AzurePublic, AzureChina, AzureUsGovernment ve AzureGermany'dir. Varsayılan olarak, veri fabrikasının bulut ortamı kullanılır.		 Hayır

Örnek

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

OAuth2 İstemci Kimlik Bilgisi kimlik doğrulamasını kullanma

authenticationType özelliğini OAuth2ClientCredential olarak ayarlayın. Önceki bölümde açıklanan genel özelliklere ek olarak aşağıdaki özellikleri belirtin:

Özellik Açıklama Gerekli
tokenEndpoint Erişim belirtecini almak için yetkilendirme sunucusunun belirteç uç noktası. Yes
clientId Uygulamanızla ilişkili istemci kimliği. Yes
clientSecret Uygulamanızla ilişkili istemci gizli dizisi. Data Factory'de güvenli bir şekilde depolamak için bu alanı SecureString türü olarak işaretleyin. Azure Key Vault'ta depolanan bir gizli diziye de başvurabilirsiniz. Yes
kapsam Gerekli erişimin kapsamı. Ne tür bir erişim isteneceğini açıklar. Hayır
kaynak Erişimin isteneceği hedef hizmet veya kaynak. Hayır

Örnek

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

Sistem tarafından atanan yönetilen kimlik kimlik doğrulamayı kullanma

authenticationType özelliğini ManagedServiceIdentity olarak ayarlayın. Önceki bölümde açıklanan genel özelliklere ek olarak aşağıdaki özellikleri belirtin:

Özellik Açıklama Gerekli
aadResourceId Yetkilendirme için istediğiniz Microsoft Entra kaynağını belirtin, örneğin, https://management.core.windows.net. Yes

Örnek

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

Kullanıcı tarafından atanan yönetilen kimlik kimlik doğrulamayı kullanma

authenticationType özelliğini ManagedServiceIdentity olarak ayarlayın. Önceki bölümde açıklanan genel özelliklere ek olarak aşağıdaki özellikleri belirtin:

Özellik Açıklama Gerekli
aadResourceId Yetkilendirme için istediğiniz Microsoft Entra kaynağını belirtin, örneğin, https://management.core.windows.net. Yes
kimlik bilgileri Kimlik bilgisi nesnesi olarak kullanıcı tarafından atanan yönetilen kimliği belirtin. Yes

Örnek

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

Kimlik doğrulama üst bilgilerini kullanma

Ayrıca, yerleşik kimlik doğrulama türleriyle birlikte kimlik doğrulaması için istek üst bilgilerini yapılandırabilirsiniz.

Örnek: API anahtarı kimlik doğrulaması kullanma

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

Veri kümesi özellikleri

Bu bölümde REST veri kümesinin desteklediği özelliklerin listesi sağlanır.

Veri kümelerini tanımlamak için kullanılabilen bölümlerin ve özelliklerin tam listesi için bkz . Veri kümeleri ve bağlı hizmetler.

REST'ten veri kopyalamak için aşağıdaki özellikler desteklenir:

Özellik Açıklama Gerekli
Tür Veri kümesinin tür özelliği RestResource olarak ayarlanmalıdır. Yes
Relativeurl Verileri içeren kaynağın göreli URL'si. Bu özellik belirtilmediğinde, yalnızca bağlı hizmet tanımında belirtilen URL kullanılır. HTTP bağlayıcısı, birleşik URL'den veri kopyalar: [URL specified in linked service]/[relative URL specified in dataset]. Hayır

veri kümesinde , additionalHeadersrequestBody ve paginationRules ayarlarını requestMethodyaparken, yeni modeli ileriye dönük etkinlikte kullanmanız önerilirken, yine de olduğu gibi desteklenir.

Örnek:

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

Kopyalama Etkinliği özellikleri

Bu bölümde REST kaynağı ve havuzu tarafından desteklenen özelliklerin listesi sağlanır.

Etkinlikleri tanımlamak için kullanılabilen bölümlerin ve özelliklerin tam listesi için bkz . İşlem hatları.

Kaynak olarak REST

Kopyalama etkinliği kaynağı bölümünde aşağıdaki özellikler desteklenir:

Özellik Açıklama Gerekli
Tür Kopyalama etkinliği kaynağının type özelliği RestSource olarak ayarlanmalıdır. Yes
requestMethod HTTP yöntemi. İzin verilen değerler GET (varsayılan) ve POST değerleridir. Hayır
additionalHeaders Ek HTTP isteği üst bilgileri. Hayır
requestBody HTTP isteğinin gövdesi. Hayır
paginationRules Sonraki sayfa isteklerini oluşturmak için sayfalandırma kuralları. Ayrıntılarla ilgili sayfalandırma desteği bölümüne bakın. Hayır
httpRequestTimeout Yanıt almak için HTTP isteğinin zaman aşımı (TimeSpan değeri). Bu değer, yanıt verilerini okumak için zaman aşımı değil, yanıt almak için zaman aşımıdır. Varsayılan değer 00:01:40'tır. Hayır
requestInterval Sonraki sayfa için isteği göndermeden önce bekleme süresi. Varsayılan değer 00:00:01'dir Hayır

Not

REST bağlayıcısı, içinde additionalHeadersbelirtilen "Accept" üst bilgisini yoksayar. REST bağlayıcısı yalnızca JSON'da yanıtı desteklediğinden, öğesinin Accept: application/jsonüst bilgisini otomatik olarak oluşturur.
Nesnenin yanıt gövdesi olarak dizisi sayfalandırmada desteklenmez.

Örnek 1: Get yöntemini sayfalandırma ile kullanma

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

Örnek 2: Post yöntemini kullanma

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

Havuz olarak REST

Kopyalama etkinliği havuzu bölümünde aşağıdaki özellikler desteklenir:

Özellik Açıklama Gerekli
Tür Kopyalama etkinliği havuzu type özelliği RestSink olarak ayarlanmalıdır. Yes
requestMethod HTTP yöntemi. İzin verilen değerler POST (varsayılan), PUT ve PATCH değerleridir. Hayır
additionalHeaders Ek HTTP isteği üst bilgileri. Hayır
httpRequestTimeout Yanıt almak için HTTP isteğinin zaman aşımı (TimeSpan değeri). Bu değer, verileri yazmak için zaman aşımı değil, yanıt almak için zaman aşımıdır. Varsayılan değer 00:01:40'tır. Hayır
requestInterval Milisaniye cinsinden farklı istekler arasındaki aralık süresi. İstek aralığı değeri [10, 60000] arasında bir sayı olmalıdır. Hayır
httpCompressionType Verileri En uygun Sıkıştırma Düzeyi ile gönderirken kullanılacak HTTP sıkıştırma türü. İzin verilen değerler hiçbiri ve gzip değerleridir. Hayır
writeBatchSize Toplu iş başına REST havuzuna yazacak kayıt sayısı. Varsayılan değer 10000'dir. Hayır

Havuz olarak REST bağlayıcısı, JSON kabul eden REST API'leriyle çalışır. Veriler JSON biçiminde aşağıdaki desenle gönderilir. Gerektiğinde, kaynak verileri REST API tarafından beklenen yüke uyacak şekilde yeniden şekillendirmek için kopyalama etkinliği şema eşlemesini kullanabilirsiniz.

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

Örnek:

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

Eşleme veri akışı özellikleri

REST, hem tümleştirme veri kümeleri hem de satır içi veri kümeleri için veri akışlarında desteklenir.

Kaynak dönüştürme

Özellik Açıklama Gerekli
requestMethod HTTP yöntemi. İzin verilen değerler GET ve POST değerleridir. Yes
Relativeurl Verileri içeren kaynağın göreli URL'si. Bu özellik belirtilmediğinde, yalnızca bağlı hizmet tanımında belirtilen URL kullanılır. HTTP bağlayıcısı, birleşik URL'den veri kopyalar: [URL specified in linked service]/[relative URL specified in dataset]. Hayır
additionalHeaders Ek HTTP isteği üst bilgileri. Hayır
httpRequestTimeout Yanıt almak için HTTP isteğinin zaman aşımı (TimeSpan değeri). Bu değer, verileri yazmak için zaman aşımı değil, yanıt almak için zaman aşımıdır. Varsayılan değer 00:01:40'tır. Hayır
requestInterval Milisaniye cinsinden farklı istekler arasındaki aralık süresi. İstek aralığı değeri [10, 60000] arasında bir sayı olmalıdır. Hayır
QueryParameters. request_query_parameter OR QueryParameters['request_query_parameter'] "request_query_parameter", bir sonraki HTTP isteği URL'sinde bir sorgu parametresi adına başvuran kullanıcı tanımlıdır. Hayır

Havuz dönüşümü

Özellik Açıklama Gerekli
additionalHeaders Ek HTTP isteği üst bilgileri. Hayır
httpRequestTimeout Yanıt almak için HTTP isteğinin zaman aşımı (TimeSpan değeri). Bu değer, verileri yazmak için zaman aşımı değil, yanıt almak için zaman aşımıdır. Varsayılan değer 00:01:40'tır. Hayır
requestInterval Milisaniye cinsinden farklı istekler arasındaki aralık süresi. İstek aralığı değeri [10, 60000] arasında bir sayı olmalıdır. Hayır
httpCompressionType Verileri En uygun Sıkıştırma Düzeyi ile gönderirken kullanılacak HTTP sıkıştırma türü. İzin verilen değerler hiçbiri ve gzip değerleridir. Hayır
writeBatchSize Toplu iş başına REST havuzuna yazacak kayıt sayısı. Varsayılan değer 10000'dir. Hayır

CRUD işlemleri için REST havuzuna gönderilecek göreli satır verilerinin yanı sıra silme, ekleme, güncelleştirme ve upsert yöntemlerini ayarlayabilirsiniz.

Data flow REST sink

Örnek veri akışı betiği

ADF'ye REST havuzunuzla ne tür bir eylem gerçekleştireceklerini bildirmek için havuz öncesinde bir değişiklik satırı dönüştürmesi kullanıldığına dikkat edin. Örneğin ekleme, güncelleştirme, upsert, silme.

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

Sayfalandırma desteği

REST API'lerinden veri kopyaladığınızda, NORMALDE REST API yanıt yükü boyutunu makul bir sayı altında tek bir istekle sınırlar; büyük miktarda veri döndürürken, sonucu birden çok sayfaya böler ve arayanların sonucun sonraki sayfasını almak için ardışık istek göndermesini gerektirir. Genellikle, bir sayfa için istek dinamiktir ve önceki sayfanın yanıtından döndürülen bilgiler tarafından oluşturulur.

Bu genel REST bağlayıcısı aşağıdaki sayfalandırma desenlerini destekler:

  • Sonraki isteğin geçerli yanıt gövdesindeki mutlak veya göreli URL = özellik değeri
  • Sonraki isteğin geçerli yanıt üst bilgilerinde mutlak veya göreli URL = üst bilgi değeri
  • Sonraki isteğin sorgu parametresi = geçerli yanıt gövdesindeki özellik değeri
  • Sonraki isteğin sorgu parametresi = geçerli yanıt üst bilgilerinde üst bilgi değeri
  • Sonraki isteğin üst bilgisi = geçerli yanıt gövdesindeki özellik değeri
  • Sonraki isteğin üst bilgisi = geçerli yanıt üst bilgilerinde üst bilgi değeri

Sayfalandırma kuralları , veri kümesinde bir veya daha fazla büyük/küçük harfe duyarlı anahtar-değer çifti içeren bir sözlük olarak tanımlanır. yapılandırma, ikinci sayfadan başlayarak isteği oluşturmak için kullanılır. Bağlayıcı, HTTP durum kodu 204 (İçerik Yok) aldığında veya "paginationRules" içindeki JSONPath ifadelerinden herhangi biri null döndürdüğünde yinelemeyi durdurur.

Sayfalandırma kurallarında desteklenen anahtarlar :

Tuş Açıklama
AbsoluteUrl Sonraki isteği vermek için URL'yi gösterir. Mutlak URL veya göreli URL olabilir.
QueryParameters. request_query_parameter OR QueryParameters['request_query_parameter'] "request_query_parameter", bir sonraki HTTP isteği URL'sinde bir sorgu parametresi adına başvuran kullanıcı tanımlıdır.
Üstbilgi. request_header OR Üst Bilgileri['request_header'] "request_header", bir sonraki HTTP isteğinde bir üst bilgi adına başvuran kullanıcı tanımlıdır.
EndCondition:end_condition "end_condition", bir sonraki HTTP isteğinde sayfalandırma döngüsünü sonlandıracak koşulu gösteren kullanıcı tanımlıdır.
MaxRequestNumber En yüksek sayfalandırma isteği numarasını gösterir. Boş bırakın, sınır yok demektir.
SupportRFC5988 Varsayılan olarak, herhangi bir sayfalandırma kuralı tanımlanmadıysa bu true olarak ayarlanır. False olarak ayarlayarak supportRFC5988 veya bu özelliği betikten kaldırarak bu kuralı devre dışı bırakabilirsiniz.

Sayfalandırma kurallarında desteklenen değerler :

Value Açıklama
Üstbilgi. response_header OR Üst Bilgileri['response_header'] "response_header", geçerli HTTP yanıtında bir üst bilgi adına başvuruda bulunan ve değeri sonraki isteği vermek için kullanılacak olan kullanıcı tanımlıdır.
"$" ile başlayan bir JSONPath ifadesi (yanıt gövdesinin kökünü temsil eder) Yanıt gövdesi yalnızca bir JSON nesnesi içermelidir ve yanıt gövdesi desteklenmediğinden nesne dizisi. JSONPath ifadesi, bir sonraki isteği vermek için kullanılacak tek bir ilkel değer döndürmelidir.

Not

Veri akışlarını eşlemedeki sayfalandırma kuralları, kopyalama etkinliğinde aşağıdaki açılardan farklıdır:

  1. Aralık, eşleme veri akışlarında desteklenmez.
  2. [''] veri akışlarını eşlemede desteklenmez. Bunun yerine, özel karakterden kaçmak için kullanın {} . Örneğin, body.{@odata.nextLink}JSON düğümü @odata.nextLink özel karakter . içeren .
  3. Bitiş koşulu, veri akışlarını eşlemede desteklenir, ancak koşul söz dizimi kopyalama etkinliğindeki söz diziminden farklıdır. body yerine yanıt gövdesini $belirtmek için kullanılır. header yerine yanıt üst bilgisini headersbelirtmek için kullanılır. Bu farkı gösteren iki örnek aşağıda verilmiştir:
    • Örnek 1:
      Kopyalama etkinliği: "EndCondition:$.data": "Empty"
      Eşleme veri akışları: "EndCondition:body.data": "Boş"
    • Örnek 2:
      Kopyalama etkinliği: "EndCondition:headers.complete": "Exist"
      Eşleme veri akışları: "EndCondition:header.complete": "Var"

Sayfalandırma kuralları örnekleri

Bu bölümde sayfalandırma kuralları ayarlarına yönelik örneklerin listesi sağlanır.

Örnek 1: QueryParameters'daki Değişkenler

Bu örnek, değişkenleri QueryParameters içinde olan birden çok istek göndermeye yönelik yapılandırma adımlarını sağlar.

Birden çok istek:

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

1. Adım: Aşağıdaki ekran görüntülerinde gösterildiği gibi Temel URL'ye veya Göreli URL'ye giriş sysparm_offset={offset} yapın:

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

veya

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

2. Adım: Sayfalandırma kurallarını seçenek 1 veya seçenek 2 olarak ayarlayın:

  • Option1: "QueryParameters.{ offset}" : "ARALIK:0:10000:1000"

  • Option2: "AbsoluteUrl.{ offset}" : "ARALIK:0:10000:1000"

Örnek 2:AbsoluteUrl'deki Değişkenler

Bu örnek, değişkenleri AbsoluteUrl'de olan birden çok istek göndermeye yönelik yapılandırma adımlarını sağlar.

Birden çok istek:

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

1. Adım: Bağlı hizmet yapılandırma sayfasındaki Temel URL'ye veya veri kümesi bağlantı bölmesinde göreli URL'ye giriş {id}.

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

veya

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

2. Adım: Sayfalandırma kurallarını "AbsoluteUrl.{ olarak ayarlayın id}" :"RANGE:1:100:1".

Örnek 3:Üst Bilgilerdeki Değişkenler

Bu örnek, değişkenleri Üst Bilgi'de olan birden çok istek göndermeye yönelik yapılandırma adımlarını sağlar.

Birden çok istek:
RequestUrl: https://example/table
İstek 1: Header(id->0)
İstek 2: Header(id->10)
......
İstek 100: Header(id->100)

1. Adım: Ek üst bilgilerde giriş{id}.

2. Adım: Sayfalandırma kurallarını "Üst Bilgiler" olarak ayarlayın. id}" : "RARNGE:0:100:10".

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

Örnek 4:Değişkenler AbsoluteUrl/QueryParameters/Headers içindedir, bitiş değişkeni önceden tanımlanmamıştır ve bitiş koşulu yanıtı temel alır

Bu örnek, değişkenleri AbsoluteUrl/QueryParameters/Headers içinde olan ancak bitiş değişkeni tanımlanmayan birden çok istek göndermeye yönelik yapılandırma adımları sağlar. Farklı yanıtlar için, örnek 4.1-4.6'da farklı bitiş koşulu kuralı ayarları gösterilir.

Birden çok istek:

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

Bu örnekte iki yanıtla karşılaşıldı:

Yanıt 1:

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

Yanıt 2:

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

1. Adım: Sayfalandırma kuralları aralığını Örnek 1 olarak ayarlayın ve aralığın sonunu "AbsoluteUrl" olarak boş bırakın. offset}": "RANGE:0::1000".

2. Adım: Farklı son yanıtlara göre farklı bitiş koşulu kuralları ayarlayın. Aşağıdaki örneklere bakın:

  • Örnek 4.1: Yanıttaki belirli düğümün değeri boş olduğunda sayfalandırma sona erer

    REST API aşağıdaki yapıdaki son yanıtı döndürür:

    {
    Data: []
}

    Yanıttaki belirli düğümün değeri boş olduğunda sayfalandırmayı sonlandırmak için bitiş koşulu kuralını "EndCondition:$.data": "Empty" olarak ayarlayın.

    Screenshot showing the End Condition setting for Example 4.1.

  • Örnek 4.2: Yanıttaki belirli düğümün değeri mevcut olmadığında sayfalandırma sona erer

    REST API aşağıdaki yapıdaki son yanıtı döndürür:

    {}

    Yanıttaki belirli düğümün değeri olmadığında sayfalandırmayı sonlandırmak için bitiş koşulu kuralını "EndCondition:$.data": "NonExist" olarak ayarlayın.

    Screenshot showing the End Condition setting for Example 4.2.

  • Örnek 4.3: Yanıttaki belirli düğümün değeri mevcut olduğunda sayfalandırma sona erer

    REST API aşağıdaki yapıdaki son yanıtı döndürür:

    {
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}

    Bitiş koşulu kuralını "EndCondition:$ olarak ayarlayın. Tamamlandı": Yanıttaki belirli düğümün değeri mevcut olduğunda sayfalandırmayı sonlandırmak için "Var" ifadesi.

    Screenshot showing the End Condition setting for Example 4.3.

  • Örnek 4.4: Yanıttaki belirli düğümün değeri kullanıcı tanımlı bir const değeri olduğunda sayfalandırma sona erer

    REST API yanıtı aşağıdaki yapıda döndürür:

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

    ......

    Ve son yanıt aşağıdaki yapıdadır:

    {
    Data: [
        {key1: val991, key2: val992
        },
        {key1: val993, key2: val994
        }
    ],
            Complete: true
}

    Bitiş koşulu kuralını "EndCondition:$ olarak ayarlayın. Complete": Yanıttaki belirli düğümün değeri kullanıcı tanımlı bir const değeri olduğunda sayfalandırmayı sonlandırmak için "Const:true" .

    Screenshot showing the End Condition setting for Example 4.4.

  • Örnek 4.5: Yanıttaki üst bilgi anahtarının değeri kullanıcı tanımlı const değerine eşit olduğunda sayfalandırma sona erer

    REST API yanıtlarındaki üst bilgi anahtarları aşağıdaki yapıda gösterilir:

    Yanıt üst bilgisi 1: header(Complete->0)
    ......
    Son Yanıt üst bilgisi: header(Complete->1)

    Bitiş koşulu kuralını "EndCondition:headers" olarak ayarlayın. Complete": Yanıttaki üst bilgi anahtarının değeri kullanıcı tanımlı const değerine eşit olduğunda sayfalandırmayı sonlandırmak için "Const:1" .

    Screenshot showing the End Condition setting for Example 4.5.

  • Örnek 4.6: Yanıt üst bilgisinde anahtar mevcut olduğunda sayfalandırma sona erer

    REST API yanıtlarındaki üst bilgi anahtarları aşağıdaki yapıda gösterilir:

    Yanıt üst bilgisi 1: header()
    ......
    Son Yanıt üst bilgisi: header(CompleteTime->20220920)

    Bitiş koşulu kuralını "EndCondition:headers" olarak ayarlayın. CompleteTime": Yanıt üst bilgisinde anahtar mevcut olduğunda sayfalandırmayı sonlandırmak için "Var" olur.

    Screenshot showing the End Condition setting for Example 4.6.

Örnek 5:Aralık kuralı tanımlanmadığında sonsuz isteklerden kaçınmak için bitiş koşulunu ayarlama

Bu örnek, aralık kuralı kullanılmadığında birden çok istek göndermeye yönelik yapılandırma adımlarını sağlar. Bitiş koşulu, sonsuz isteklerden kaçınmak için Örnek 4.1-4.6'ya başvurabilir. REST API aşağıdaki yapıda yanıt döndürür; bu durumda sonraki sayfanın URL'si disk belleği.next ile gösterilir.

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

Son yanıt:

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

1. Adım: Sayfalandırma kurallarını "AbsoluteUrl" olarak ayarlayın: "$.paging.next".

2. Adım: Son yanıtta her zaman son istek URL'si ile aynıysa next ve boş değilse, sonsuz istekler gönderilir. Bitiş koşulu sonsuz isteklerden kaçınmak için kullanılabilir. Bu nedenle, bitiş koşulu kuralını ayarlamak için Örnek 4.1-4.6'ya bakın.

Örnek 6:Sonsuz istekten kaçınmak için maksimum istek numarasını ayarlayın

Aşağıdaki ekran görüntüsünde gösterildiği gibi sonsuz istekten kaçınmak için MaxRequestNumber değerini ayarlayın:

Screenshot showing the Max Request Number setting for Example 6.

Örnek 7:RFC 5988 sayfalandırma kuralı varsayılan olarak desteklenir

Arka uç, üst bilgideki RFC 5988 stil bağlantılarını temel alan bir sonraki URL'yi otomatik olarak alır.

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

İpucu

Bu varsayılan sayfalandırma kuralını etkinleştirmek istemiyorsanız, bunu betikte ayarlayabilir supportRFC5988false veya silebilirsiniz.

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

Örnek 8: Sonraki istek URL'si, eşleme veri akışlarında sayfalandırma kullanıldığında yanıt gövdesindendir

Bu örnekte, sonraki istek URL'si yanıt gövdesinden olduğunda eşleme veri akışlarında sayfalandırma kuralının ve bitiş koşulu kuralının nasıl ayarlanacağı belirtilir.

Yanıt şeması aşağıda gösterilmiştir:

Screenshot showing the response schema of Example 8.

Sayfalandırma kuralları aşağıdaki ekran görüntüsü olarak ayarlanmalıdır:

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

Varsayılan olarak, sayfalandırma gövde olduğunda durur. {@odata.nextLink}** null veya boş.

Ancak son yanıt gövdesindeki @odata.nextLink değeri son istek URL'sine eşitse sonsuz döngüye yol açar. Bu koşulu önlemek için bitiş koşulu kurallarını tanımlayın.

  • Son yanıttaki Değer Boş ise bitiş koşulu kuralı aşağıdaki gibi ayarlanabilir:

    Screenshot showing setting the end condition rule when the last response is empty.

  • Yanıt üst bilgisindeki tam anahtarın değeri true değerine eşitse sayfalandırmanın sonunu gösteriyorsa, bitiş koşulu kuralı aşağıdaki gibi ayarlanabilir:

    Screenshot showing setting the end condition rule when the complete key in the response header equals to true indicates the end of pagination.

Örnek 9: Veri akışlarını eşlemede sayfalandırma kullanıldığında yanıt biçimi XML ve sonraki istek URL'si yanıt gövdesindendir

Bu örnekte, yanıt biçimi XML ve sonraki istek URL'si yanıt gövdesinden olduğunda eşleme veri akışlarında sayfalandırma kuralının nasıl ayarlanacağı belirtilir. Aşağıdaki ekran görüntüsünde gösterildiği gibi, ilk URL https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

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

Yanıt şeması aşağıda gösterilmiştir:

Screenshot showing the response schema of Example 9.

Sayfalandırma kuralı söz dizimi Örnek 8 ile aynıdır ve bu örnekte aşağıdaki gibi ayarlanmalıdır:

Screenshot showing setting the pagination rule for Example 9.

JSON yanıtlarını olduğu gibi dışarı aktarma

Rest API JSON yanıtlarını olduğu gibi çeşitli dosya tabanlı depolara aktarmak için bu REST bağlayıcısını kullanabilirsiniz. Böyle bir şemadan bağımsız kopya elde etmek için veri kümesindeki "yapı" (şema olarak da adlandırılır) bölümünü ve kopyalama etkinliğindeki şema eşlemesini atlayın.

Şema eşleme

REST uç noktasından tablo havuzuna veri kopyalamak için şema eşlemeye bakın.

İlgili içerik

Kopyalama Etkinliği'nin Azure Data Factory'de kaynak ve havuz olarak desteklediği veri depolarının listesi için bkz . Desteklenen veri depoları ve biçimleri.