Копирование и преобразование данных из конечной точки REST и обратно с помощью Фабрики данных Azure

  • Статья

Область применения:Фабрика данных Azure Azure Synapse Analytics

Совет

Попробуйте использовать фабрику данных в Microsoft Fabric, решение для аналитики с одним интерфейсом для предприятий. Microsoft Fabric охватывает все, от перемещения данных до обработки и анализа данных в режиме реального времени, бизнес-аналитики и отчетности. Узнайте, как бесплатно запустить новую пробную версию !

В этой статье описывается, как с помощью действия копирования в фабрике данных Azure копировать данные из конечной точки REST и обратно. Это продолжение статьи о действии копирования в Фабрике данных Azure, в которой представлены общие сведения о действии копирования.

Между соединителем REST, соединителем HTTP и соединителем веб-таблиц существуют следующие различия:

  • Соединитель REST поддерживает копирование данных из API RESTful.
  • Соединитель HTTP применяется для извлечения данных из любой конечной точки HTTP, например, для скачивания файла. Перед использованием этого соединителя REST вы можете использовать соединитель HTTP для копирования данных из API RESTful, что поддерживается, но менее функционально по сравнению с соединителем REST.
  • Соединитель веб-таблиц извлекает содержимое таблицы со страницы HTML.

Поддерживаемые возможности

Соединитель REST поддерживает следующие возможности:

Поддерживаемые возможности IR
Действие копирования (источник/приемник) (1) (2)
Поток данных для сопоставления (источник/приемник) (1)

① Среда выполнения интеграции Azure ② Локальная среда выполнения интеграции

Список хранилищ данных, которые поддерживаются в качестве источников/приемников, см. в разделе Поддерживаемые хранилища данных.

Этот универсальный соединитель REST, в частности, поддерживает следующее.

  • Копирование данных из конечной точки REST с помощью методов GET или POST и копирование данных в конечную точку REST с помощью методов POST, PUT или PATCH.
  • Копирование данных с помощью одного из следующих методов проверки подлинности: Анонимный, Базовый, Субъект-служба, Учетные данные клиента OAuth2, управляемое удостоверение, назначаемое системой и управляемое удостоверение, назначаемое пользователем.
  • Разбиение на страницы в интерфейсах REST API.
  • Если источником является REST: копирование ответа JSON REST как в локальной среде или его анализ с помощью сопоставления схем. Поддерживаются только полезные данные ответа в JSON.

Совет

Чтобы проверить запрос для извлечения данных, прежде чем настраивать соединитель REST в Фабрике данных, ознакомьтесь с требованиями спецификации API в отношении заголовка и текста. Для проверки можно использовать такие средства, как Postman или веб-браузер.

Необходимые компоненты

Если хранилище данных размещено в локальной сети, виртуальной сети Azure или виртуальном частном облаке Amazon, для подключения к нему нужно настроить локальную среду выполнения интеграции.

Если же хранилище данных представляет собой управляемую облачную службу данных, можно использовать Azure Integration Runtime. Если доступ предоставляется только по IP-адресам, утвержденным в правилах брандмауэра, вы можете добавить IP-адреса Azure Integration Runtime в список разрешений.

Вы также можете использовать функцию среды выполнения интеграции в управляемой виртуальной сети в Фабрике данных Azure для доступа к локальной сети без установки и настройки локальной среды выполнения интеграции.

Дополнительные сведения о вариантах и механизмах обеспечения сетевой безопасности, поддерживаемых Фабрикой данных, см. в статье Стратегии получения доступа к данным.

Начать

Чтобы выполнить действие копирования с конвейером, можно воспользоваться одним из приведенных ниже средств или пакетов SDK:

Создание связанной службы REST с помощью пользовательского интерфейса

Выполните приведенные ниже действия, чтобы создать связанную службу для REST в пользовательском интерфейсе портала Azure.

  1. Перейдите на вкладку "Управление" в Фабрике данных Azure или рабочей области Synapse и выберите "Связанные службы", затем щелкните "Создать".

  2. Выполните поиск REST и выберите соединитель REST.

    Select REST connector.

  3. Настройте сведения о службе, проверьте подключение и создайте связанную службу.

    Configure REST linked service.

Сведения о конфигурации соединителя

В разделах ниже приведены сведения о свойствах, которые используются для определения сущностей Фабрики данных, относящихся к соединителю REST.

Свойства связанной службы

Для связанной службы REST поддерживаются следующие свойства.

Свойство Описание: Обязательное поле
type Для свойства type необходимо задать значение RestService. Да
URL-адрес Базовый URL-адрес службы REST. Да
enableServerCertificateValidation Следует ли проверять TLS/SSL-сертификат на стороне сервера при подключении к конечной точке. No
(значение по умолчанию true)
authenticationType Тип проверки подлинности, используемый для подключения к службе REST. Допустимые значения: Anonymous, Basic, AadServicePrincipal, OAuth2ClientCredential и ManagedServiceIdentity. Кроме того, можно настроить заголовки проверки подлинности в свойстве authHeaders. Обратитесь к соответствующим разделам ниже, в которых описываются дополнительные свойства и примеры. Да
authHeaders Дополнительные заголовки HTTP-запросов для проверки подлинности.
Например, чтобы использовать проверку подлинности с помощью ключа API, можно выбрать тип проверки подлинности "Анонимный" и указать ключ API в заголовке.		 No
connectVia Среда выполнения интеграции, используемая для подключения к хранилищу данных. Дополнительные сведения см. в разделе Предварительные условия. Если не указано другое, это свойство по умолчанию использует интегрированную среду выполнения Azure. No

Сведения о различных типах проверки подлинности см. в соответствующих разделах.

Использование обычной проверки подлинности

Задайте для свойства authenticationType значение Basic. В дополнение к общим свойствам, описанных в предыдущих разделах, укажите следующие свойства:

Свойство Описание: Обязательное поле
userName Имя пользователя для доступа к конечной точке REST. Да
password Пароль для пользователя (значение userName). Пометьте это поле как SecureString, чтобы безопасно хранить его в фабрике данных. Вы можете также указать секрет, хранящийся в Azure Key Vault. Да

Пример

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

Использование проверки подлинности субъекта-службы

Задайте для свойства authenticationType значение AadServicePrincipal. В дополнение к общим свойствам, описанных в предыдущих разделах, укажите следующие свойства:

Свойство Описание: Обязательное поле
servicePrincipalId Укажите идентификатор клиента приложения Microsoft Entra. Да
servicePrincipalKey Укажите ключ приложения Microsoft Entra. Пометьте это поле как SecureString, чтобы безопасно хранить его в фабрике данных, или добавьте ссылку на секрет, хранящийся в Azure Key Vault. Да
tenant Укажите сведения о клиенте (доменное имя или идентификатор клиента), в котором находится приложение. Его можно получить, наведя указатель мыши на правый верхний угол страницы портала Azure. Да
aadResourceId Укажите ресурс Microsoft Entra, запрашивающий авторизацию, например https://management.core.windows.net. Да
azureCloudType Для проверки подлинности субъекта-службы укажите тип облачной среды Azure, в которой зарегистрировано приложение Microsoft Entra.
Допустимые значения: AzurePublic, AzureChina, AzureUsGovernment и AzureGermany. По умолчанию используется облачная среда Фабрики данных.		 No

Пример

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

Использование проверки подлинности учетных данных клиента OAuth2

Задайте для свойства authenticationType значение OAuth2ClientCredential. В дополнение к общим свойствам, описанных в предыдущих разделах, укажите следующие свойства:

Свойство Описание: Обязательное поле
tokenEndpoint Конечная точка маркера сервера авторизации для получения маркера доступа. Да
clientId Идентификатор клиента, связанный с приложением. Да
clientSecret Секрет клиента, связанный с приложением. Пометьте это поле как SecureString, чтобы безопасно хранить его в фабрике данных. Вы можете также указать секрет, хранящийся в Azure Key Vault. Да
область Область необходимого доступа. Описывает, какой тип доступа будет запрашиваться. No
resource Целевая служба или ресурс, к которым будет запрашиваться доступ. No

Пример

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

Использование проверки подлинности управляемого удостоверения, назначаемого системой

Задайте для свойства authenticationType значение ManagedServiceIdentity. В дополнение к общим свойствам, описанных в предыдущих разделах, укажите следующие свойства:

Свойство Описание: Обязательное поле
aadResourceId Укажите ресурс Microsoft Entra, запрашивающий авторизацию, например https://management.core.windows.net. Да

Пример

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

Проверка подлинности с помощью управляемого удостоверения, назначаемого системой

Задайте для свойства authenticationType значение ManagedServiceIdentity. В дополнение к общим свойствам, описанных в предыдущих разделах, укажите следующие свойства:

Свойство Описание: Обязательное поле
aadResourceId Укажите ресурс Microsoft Entra, запрашивающий авторизацию, например https://management.core.windows.net. Да
учетные данные Укажите назначаемое пользователем управляемое удостоверение в качестве объекта учетных данных. Да

Пример

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

Использование заголовков проверки подлинности

Кроме того, можно настроить заголовки запроса для проверки подлинности вместе со встроенными типами проверки подлинности.

Пример. Использование проверки подлинности ключа API

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

Свойства набора данных

Этот раздел содержит список свойств, поддерживаемых набором данных REST.

Полный список разделов и свойств, используемых для определения наборов данных, приведен в статье Наборы данных и связанные службы в фабрике данных Azure.

Для копирования данных из REST поддерживаются следующие свойства.

Свойство Описание: Обязательное поле
type Для свойства type набора данных необходимо задать значение RestResource. Да
relativeUrl Относительный URL-адрес ресурса, который содержит данные. Если свойство не задано, используется только URL-адрес, указанный в определении связанной службы. HTTP-соединитель копирует данные из объединенного URL-адреса: [URL specified in linked service]/[relative URL specified in dataset]. No

Если вы ранее настраивали requestMethod, additionalHeaders, requestBody и paginationRules в наборе данных, он пока поддерживается и не требует изменений, но мы рекомендуем использовать новую модель в предстоящем действии.

Пример:

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

Свойства действия копирования

Этот раздел содержит список свойств, поддерживаемых источником и приемником REST.

Полный список разделов и свойств, доступных для определения действий, см. в статье, посвященной конвейерам и действиям в Фабрике данных Azure.

REST в качестве источника

В разделе source действия копирования поддерживаются следующие свойства:

Свойство Описание: Обязательное поле
type Свойство type источника действия копирования должно иметь значение RestSource. Да
requestMethod Метод HTTP. Допустимые значения: GET (по умолчанию) и POST. No
additionalHeaders Дополнительные заголовки HTTP-запроса. No
requestBody Текст HTTP-запроса. No
paginationRules Правила разбиения на страницы для составления следующих запросов страниц. Дополнительные сведения см. в разделе, посвященном поддержке разбиения на страницы. No
httpRequestTimeout Время ожидания (значение Временной диапазон) ответа для HTTP-запроса. Это значение является интервалом времени для получения ответа, а не считывания данных ответа. По умолчанию используется значение 00:01:40. No
requestInterval Время ожидания перед отправкой запроса следующей страницы. Значение по умолчанию — 00:00:01 No

Примечание.

Соединитель REST игнорирует любой заголовок Accept, указанный в additionalHeaders. Так как соединитель REST поддерживает только ответ в JSON, он автоматически создает заголовок Accept: application/json.
Массив объекта в виде текста отклика не поддерживается в разбиении на страницы.

Пример 1. Использование метода Get с разбиением на страницы

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

Пример 2. Использование метода POST

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

REST как приемник

В разделе sink действия копирования поддерживаются следующие свойства:

Свойство Описание: Обязательное поле
type Свойство type для приемника действия копирования должно иметь значение RestSink. Да
requestMethod Метод HTTP. Допустимые значения: POST (по умолчанию), PUT и PATCH. No
additionalHeaders Дополнительные заголовки HTTP-запроса. No
httpRequestTimeout Время ожидания (значение Временной диапазон) ответа для HTTP-запроса. Это значение является интервалом времени для получения ответа, а не для записи данных. По умолчанию используется значение 00:01:40. No
requestInterval Интервал времени между разными запросами в миллисекундах. Интервал между запросами должен быть выражен числом в диапазоне от 10 до 60000. No
httpCompressionType Тип сжатия HTTP для использования при отправке данных с оптимальным уровнем сжатия. Допустимые значения: None и gzip. No
writeBatchSize Количество записей для записи в приемник REST на пакет. Значение по умолчанию — 10000. No

Соединитель REST в качестве приемника работает с API REST, принимающими JSON. Данные будут отправляться в JSON по следующему шаблону. При необходимости можно использовать сопоставление схем в действии копирования, чтобы изменить форму исходных данных в соответствии с ожидаемыми полезными данными API REST.

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

Пример:

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

Свойства потока данных для сопоставления

Интерфейс REST поддерживается в потоках данных как для интеграции наборов данных, так и для встроенных наборов данных.

Преобразование источника

Свойство Описание: Обязательное поле
requestMethod Метод HTTP. Допустимые значения: GET и POST. Да
relativeUrl Относительный URL-адрес ресурса, который содержит данные. Если свойство не задано, используется только URL-адрес, указанный в определении связанной службы. HTTP-соединитель копирует данные из объединенного URL-адреса: [URL specified in linked service]/[relative URL specified in dataset]. No
additionalHeaders Дополнительные заголовки HTTP-запроса. No
httpRequestTimeout Время ожидания (значение Временной диапазон) ответа для HTTP-запроса. Это значение является интервалом времени для получения ответа, а не для записи данных. По умолчанию используется значение 00:01:40. No
requestInterval Интервал времени между разными запросами в миллисекундах. Интервал между запросами должен быть выражен числом в диапазоне от 10 до 60000. No
QueryParameters.параметр_запроса_запроса ИЛИ QueryParameters['параметр_запроса_запроса'] "параметр_запроса_запроса" определяется пользователем и ссылается на одно имя параметра запроса в URL-адресе следующего запроса HTTP. No

Преобразование приемника

Свойство Описание: Обязательное поле
additionalHeaders Дополнительные заголовки HTTP-запроса. No
httpRequestTimeout Время ожидания (значение Временной диапазон) ответа для HTTP-запроса. Это значение является интервалом времени для получения ответа, а не для записи данных. По умолчанию используется значение 00:01:40. No
requestInterval Интервал времени между разными запросами в миллисекундах. Интервал между запросами должен быть выражен числом в диапазоне от 10 до 60000. No
httpCompressionType Тип сжатия HTTP для использования при отправке данных с оптимальным уровнем сжатия. Допустимые значения: None и gzip. No
writeBatchSize Количество записей для записи в приемник REST на пакет. Значение по умолчанию — 10000. No

Вы можете задать методы delete (удалить), insert (вставить), update (обновить) и upsert (обновить или вставить), а также соответствующие данные строки для отправки в приемник REST для операций CRUD.

Data flow REST sink

Простой скрипт потока данных

Обратите внимание на использование преобразования строки ALTER до приемника, чтобы указать ADF, какой тип действия следует использовать с приемником REST. Т. е. insert, update, upsert, delete.

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

Поддержка разбивки на страницы

При копировании данных из REST API, как правило, REST API ограничивает размер полезных данных ответа одного запроса в разумном количестве; при возврате большого объема данных он разбивает результат на несколько страниц и требует, чтобы вызывающие пользователи отправляли последовательные запросы, чтобы получить следующую страницу результата. Обычно запрос одной страницы является динамическим и состоит из сведений, возвращенных из ответа предыдущей страницы.

Этот универсальный соединитель REST поддерживает следующие шаблоны разбиения на страницы:

  • абсолютный или относительный URL-адрес следующего запроса = значение свойства в текущем тексте ответа;
  • абсолютный или относительный URL-адрес следующего запроса = значение заголовка в текущих заголовках ответа;
  • параметр запроса следующего запроса = значение свойства в текущем тексте ответа;
  • параметр запроса следующего запроса = значение заголовка в текущих заголовках ответа;
  • заголовок следующего запроса = значение свойства в текущем тексте ответа;
  • заголовок следующего запроса = значение заголовка в текущих заголовках ответа.

Правила разбиения на страницы определяются как словарь в наборе данных, который содержит одну пару "ключ–значение" или несколько с учетом регистра. Эта конфигурация будет использоваться для создания запроса, начиная со второй страницы. Соединитель будет прекращать итерацию при получении кода состояния HTTP 204 (Нет содержимого) или при возвращении значения null любым из выражений JSONPath в paginationRules.

Поддерживаемые ключи в правилах разбиения на страницы

Ключ. Description
AbsoluteUrl Указывает URL-адрес для выполнения следующего запроса. Это может быть абсолютный или относительный URL-адрес.
QueryParameters.параметр_запроса_запроса ИЛИ QueryParameters['параметр_запроса_запроса'] "параметр_запроса_запроса" определяется пользователем и ссылается на одно имя параметра запроса в URL-адресе следующего запроса HTTP.
Headers.заголовок_запроса ИЛИ Headers['заголовок_запроса'] "заголовок_запроса" определяется пользователем и ссылается на одно имя заголовка в следующем запросе HTTP.
EndCondition:end_condition "end_condition" определяется пользователем и указывает условие, которое завершит цикл разбиения на страницы в следующем HTTP-запросе.
MaxRequestNumber Указывает максимальное число запросов разбиения на страницы. Если оставить его пустым, число будет неограниченным.
SupportRFC5988 По умолчанию задано значение true, если правило разбиения на страницы не определено. Вы можете отключить это правило, задав для supportRFC5988 значение false или удалив это свойство из скрипта.

Поддерживаемые значения в правилах разбиения на страницы

значение Описание
Headers.заголовок_ответа ИЛИ Headers['заголовок_ответа'] "заголовок_ответа" определяется пользователем и ссылается на одно имя заголовка в текущем ответе HTTP, значение которого будет использоваться для выдачи следующего запроса.
Выражение JSONPath, начинающееся с $ (представляет корневую часть текста ответа) Текст ответа должен содержать только один объект JSON и массив объекта, так как текст ответа не поддерживается. Выражение JSONPath должно возвращать одно значение-примитив, которое будет использоваться для выдачи следующего запроса.

Примечание.

Правила разбиения на страницы в потоках данных для сопоставления отличаются от них в действиях копирования в следующих аспектах:

  1. Диапазон не поддерживается в потоках данных для сопоставления.
  2. [''] не поддерживается в потоках данных для сопоставления. Используйте {}, чтобы экранировать специальный символ, например body.{@odata.nextLink}, узел JSON @odata.nextLink которого содержит специальный символ ..
  3. Условие завершения поддерживается в потоках данных для сопоставления, но синтаксис условия отличается от него в действии копирования. body используется для указания текста ответа (вместо $). header используется для указания заголовка ответа (вместо headers). Ниже приведены два примера, показывающие это различие:
    • Пример 1:
      Действие копирования: "EndCondition:$.data": "Empty"
      Потоки данных для сопоставления: "EndCondition:body.data": "Empty"
    • Пример 2:
      Действие копирования: "EndCondition:headers.complete": "Exist"
      Потоки данных для сопоставления: "EndCondition:header.complete": "Exist"

Примеры правил разбиения на страницы

В этом разделе приводится список примеров для параметров правил разбиения на страницы.

Пример 1. Переменные в QueryParameters

В этом примере приведены шаги настройки для отправки нескольких запросов, переменные которых находятся в QueryParameters.

Несколько запросов:

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

Шаг 1. Введите sysparm_offset={offset} в поле Базовый URL-адрес или Относительный URL-адрес, как показано на следующих снимках экрана:

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

or

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

Шаг 2. Задайте правила разбиения на страницы, как указано в варианте 1 или варианте 2:

  • Вариант 1: "QueryParameters.{offset}" : "RANGE:0:10000:1000"

  • Вариант 2: "AbsoluteUrl.{offset}" : "RANGE:0:10000:1000"

Пример 2. Переменные в AbsoluteUrl

В этом примере приведены шаги настройки для отправки нескольких запросов, переменные которых находятся в AbsoluteUrl.

Несколько запросов:

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

Шаг 1. Введите {id} в поле Базовый URL-адрес на странице настройки связанной службы или в поле Относительный URL-адрес в области подключения к набору данных.

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

or

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

Шаг 2. Задайте правила разбиения на страницы как "AbsoluteUrl.{id}" :"RANGE:1:100:1".

Пример 3. Переменные в Headers

В этом примере приведены шаги настройки для отправки нескольких запросов, переменные которых находятся в заголовках.

Несколько запросов:
RequestUrl: https://example/table
Запрос 1: Header(id->0)
Запрос 2: Header(id->10)
......
Запрос 100: Header(id->100)

Шаг 1. Введите {id} в поле Дополнительные заголовки.

Шаг 2. Задайте правила разбиения на страницы как "Headers.{id}" : "RARNGE:0:100:10".

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

Пример 4. Переменные находятся в AbsoluteUrl/QueryParameters/Headers, конечная переменная не определена предварительно, а условие завершения основано на ответе

В этом примере приведены шаги по настройке для отправки нескольких запросов, переменные которых находятся в AbsoluteUrl/QueryParameters/Headers, но конечная переменная не определена. Для различных ответов в примерах 4.1–4.6 приведены различные параметры правил для условия завершения.

Несколько запросов:

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

В этом примере встречаются два ответа:

Ответ 1:

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

Ответ 2:

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

Шаг 1. Задайте диапазон правил разбиения на страницы, как показано в примере 1, и оставьте конец диапазона пустым в виде "AbsoluteUrl.{offset}": "RANGE:0::1000".

Шаг 2. Задайте разные правила условий завершения в зависимости от последнего ответа. См. примеры ниже:

  • Пример 4.1. Разбиение на страницы завершается, если значение определенного узла в ответе пусто

    REST API возвращает последний ответ в следующей структуре:

    {
    Data: []
}

    Задайте правило условия завершения как "EndCondition:$.data": "Empty", чтобы завершить разбиение на страницы в том случае, если значение определенного узла в ответе пусто.

    Screenshot showing the End Condition setting for Example 4.1.

  • Пример 4.2. Разбиение на страницы завершается, если значение определенного узла в ответе не существует

    REST API возвращает последний ответ в следующей структуре:

    {}

    Задайте правило условия завершения как "EndCondition:$.data": "NonExist", чтобы завершить разбиение на страницы в том случае, если значение определенного узла в ответе не существует.

    Screenshot showing the End Condition setting for Example 4.2.

  • Пример 4.3. Разбиение на страницы завершается, если существует значение определенного узла в ответе

    REST API возвращает последний ответ в следующей структуре:

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

    Задайте правило условия завершения как "EndCondition:$.Complete": "Exist", чтобы завершить разбиение на страницы в том случае, если существует значение определенного узла в ответе.

    Screenshot showing the End Condition setting for Example 4.3.

  • Пример 4.4. Разбиение на страницы завершается, если значение определенного узла в ответе равно определенному пользователем постоянному значению

    REST API возвращает ответ в следующей структуре:

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

    ......

    А последний ответ имеет следующую структуру:

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

    Задайте правило условия завершения как "EndCondition:$.Complete": "Const:true", чтобы завершить разбиение на страницы в том случае, если значение определенного узла в ответе равно определенному пользователем постоянному значению.

    Screenshot showing the End Condition setting for Example 4.4.

  • Пример 4.5. Разбиение на страницы завершается, если значение ключа заголовка в ответе равно определенному пользователем постоянному значению

    Ключи заголовков в ответах REST API показаны в следующей структуре:

    Заголовок ответа 1: header(Complete->0)
    ......
    Последний заголовок ответа: header(Complete->1)

    Задайте правило условия завершения как "EndCondition:headers.Complete": "Const:1", чтобы завершить разбиение на страницы в том случае, если значение ключа заголовка в ответе равно определенному пользователем постоянному значению.

    Screenshot showing the End Condition setting for Example 4.5.

  • Пример 4.6. Разбиение на страницы завершается, если ключ существует в заголовке ответа

    Ключи заголовков в ответах REST API показаны в следующей структуре:

    Заголовок ответа 1: header()
    ......
    Последний заголовок ответа: header(CompleteTime->20220920)

    Задайте правило условия завершения как "EndCondition:headers.CompleteTime": "Exist", чтобы завершить разбиение на страницы в том случае, если ключ существует в заголовке ответа.

    Screenshot showing the End Condition setting for Example 4.6.

Пример 5. Установка условия завершения для предотвращения бесконечных запросов, если правило диапазона не определено

Этот пример содержит шаги настройки для отправки нескольких запросов, если правило диапазона не используется. Чтобы избежать бесконечных запросов, можно задать условие завершения, как показано в примерах 4.1–4.6. REST API возвращает ответ со следующей структурой. В этом случае URL-адрес следующей странице представлен в paging.next.

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

Последний ответ:

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

Шаг 1. Задайте правила разбиения на страницы как "AbsoluteUrl": "$.paging.next".

Шаг 2. Если next в последнем ответе постоянно равен последнему URL-адресу запроса и не пуст, будут отправляться бесконечные запросы. Чтобы избежать бесконечных запросов, можно использовать условие завершения. Поэтому задайте правило условия завершения, как показано в примерах 4.1–4.6.

Пример 6. Установка максимального числа запросов для недопущения бесконечных запросов

Настройте MaxRequestNumber, чтобы не допустить бесконечные запросы, как показано на следующем снимке экрана:

Screenshot showing the Max Request Number setting for Example 6.

Пример 7. Правило разбиения на страницы RFC 5988 поддерживается по умолчанию

Серверная часть будет автоматически получать следующий URL-адрес с учетом ссылок в стиле RFC 5988 в заголовке.

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

Совет

Если вы не хотите включать это правило разбиения на страницы по умолчанию, можно задать для supportRFC5988 значение false или просто удалить его в скрипте.

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

Пример 8. Следующий URL-адрес запроса находится в тексте ответа при использовании разбиения на страницы в потоках данных для сопоставления

В этом примере показано, как задать правило разбиения на страницы и правило условия завершения в потоках данных для сопоставления, если следующий URL-адрес запроса находится в тексте ответа.

Схема ответа приведена ниже:

Screenshot showing the response schema of Example 8.

Правила разбиения на страницы должны быть заданы так, как показано на следующем снимке экрана:

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

По умолчанию разбиение на страницы останавливается при создании текста. {@odata.nextLink}** имеет значение NULL или пусто.

Но если значение @odata.nextLink в последнем тексте ответа равно URL-адресу последнего запроса, это приведет к бесконечному циклу. Чтобы избежать этого условия, определите правила условий завершения.

  • Если значение в последнем ответе пусто, правило условия завершения можно задать следующим образом:

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

  • Если значение полного ключа в заголовке ответа равно true (что означает завершение разбиения на страницы), правило условия завершения можно задать следующим образом:

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

Пример 9. В ответе используется формат XML, а следующий URL-адрес запроса находится в тексте ответа при использовании разбиения на страницы в потоках данных для сопоставления

В этом примере показано, как задать правило разбиения на страницы в потоках данных для сопоставления, если в ответе используется формат XML, а следующий URL-адрес запроса находится в тексте ответа. Как показано на следующем снимке экрана, первый URL-адрес — https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

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

Схема ответа приведена ниже:

Screenshot showing the response schema of Example 9.

Синтаксис правила разбиения на страницы такой же, как и в примере 8, и должен быть задан следующим образом:

Screenshot showing setting the pagination rule for Example 9.

Экспорт ответа JSON "как есть"

Вы можете использовать этот соединитель REST для экспорта ответа JSON REST API "как есть" в различные файловые хранилища. Для такого независимого от схемы копирования пропустите раздел "структура" (также называемый схема) в наборе данных и сопоставление схемы в действии копирования.

Сопоставление схемы

Инструкции по копированию данных из конечной точки REST в табличный приемник см. в разделе о сопоставлении схем.

Связанный контент

В разделе Поддерживаемые хранилища данных и форматы приведен список хранилищ данных, которые поддерживаются в качестве источников и приемников для действия копирования в Фабрике данных Azure.