Copia y transformación de datos desde y hacia un punto de conexión de REST mediante Azure Data Factory

SE APLICA A: Azure Data Factory Azure Synapse Analytics

Sugerencia

Pruebe Data Factory en Microsoft Fabric, una solución de análisis todo en uno para empresas. Microsoft Fabric abarca todo, desde el movimiento de datos hasta la ciencia de datos, el análisis en tiempo real, la inteligencia empresarial y los informes. Aprenda a iniciar una nueva evaluación gratuita.

En este artículo se explica el uso de la actividad de copia de Azure Data Factory para copiar datos desde un punto de conexión de REST y hacia allí. El artículo se basa en la actividad de copia en Azure Data Factory, que presenta una introducción general a la actividad de copia.

La diferencia entre este conector REST, el conector HTTP y el conector de tabla web son:

• El conector REST admite específicamente la copia de datos de las API de RESTful.
• El conector HTTP es genérico para recuperar datos de cualquier punto de conexión HTTP, por ejemplo, para descargar el archivo. Antes que este conector REST, puede usar el conector HTTP para copiar datos de API de RESTful, lo que se admite, pero es menos funcional en comparación con el conector REST.
• El conector de tabla web extrae el contenido de la tabla de una página web HTML.

Funcionalidades admitidas

El conector REST es compatible con las siguientes funcionalidades:

Funcionalidades admitidas	IR
Actividad de copia (origen/receptor)	1 2
Mapeo de flujo de datos (origen y destino)	①

(1) Entorno de ejecución de integración de Azure (2) Entorno de ejecución de integración autohospedado

Para obtener una lista de almacenes de datos que se admiten como orígenes o receptores, consulte Almacenes de datos admitidos.

En concreto, este conector REST genérico admite lo siguiente:

• Copiar datos desde un punto de conexión REST mediante los métodos GET o POST y copiar datos en un punto de conexión REST mediante los métodos POST, PUT o PATCH .
• Copia de datos mediante una de las siguientes autenticaciones: Anonymous, Basic, Service Principal, OAuth2 Client Credential, System Assigned Managed Identity y User Assigned Managed Identity.
• Paginación en las API de REST.
• Para REST como origen, copie la respuesta JSON de REST as-is o anótela mediante la asignación de esquemas. Solo se admite la carga de respuesta en formato JSON.

Sugerencia

Para probar una solicitud REST para la recuperación de datos antes de configurar el conector REST en Data Factory, obtenga información sobre la especificación de API para los requisitos del cuerpo y del encabezado. Puede usar herramientas como Visual Studio, Invoke-RestMethod de PowerShell o un explorador web para validar.

Requisitos previos

Si el almacén de datos se encuentra dentro de una red local, una red virtual de Azure o una nube privada virtual de Amazon, debe configurar un entorno de ejecución de integración autohospedado para conectarse a él.

Si el almacén de datos es un servicio de datos en la nube administrado, puede usar Azure Integration Runtime. Si el acceso está restringido a las direcciones IP aprobadas en las reglas de firewall, puede agregar direcciones IP de Azure Integration Runtime a la lista de permitidos.

También puede usar la característica managed virtual network integration runtime en Azure Data Factory para acceder a la red local sin instalar ni configurar un entorno de ejecución de integración autohospedado.

Para obtener más información sobre los mecanismos y opciones de seguridad de red compatibles con Data Factory, consulte Estrategias de acceso a datos.

Primeros pasos

Para realizar la actividad de copia con una canalización, puede usar una de los siguientes herramientas o SDK:

• Herramienta Copiar datos
• Azure Portal
• SDK de .NET
• SDK de Python
• Azure PowerShell
• REST API
• Plantilla de Azure Resource Manager

Creación de un servicio vinculado REST mediante la interfaz de usuario

Siga estos pasos para crear un servicio vinculado REST en la interfaz de usuario de Azure Portal.

1. Vaya a la pestaña Administrar de su área de trabajo de Azure Data Factory o Synapse, y seleccione Servicios vinculados; a continuación, seleccione Nuevo:

   Azure Data Factory

   

   Azure Synapse

   

2. Busque REST y seleccione el conector de REST.

   

3. Configure los detalles del servicio, pruebe la conexión y cree el servicio vinculado.

   

Detalles de configuración del conector

En las secciones siguientes se proporcionan detalles sobre las propiedades que puede usar para definir entidades de Data Factory específicas del conector REST.

Propiedades del servicio vinculado

Las siguientes propiedades son compatibles con el servicio vinculado de REST:

Propiedad	Descripción	Obligatorio
tipo	La propiedad type debe establecerse en RestService.	Sí
url	La dirección URL base del servicio REST.	Sí
enableServerCertificateValidation	Si se debe validar el certificado TLS/SSL del lado servidor al conectarse al punto de conexión.	No (el valor predeterminado es true)
Tipo de autenticación	El tipo de autenticación usado para conectarse al servicio REST. Los valores permitidos son Anonymous, Basic, AadServicePrincipal, OAuth2ClientCredential y ManagedServiceIdentity. Además, puede configurar encabezados de autenticación en la propiedad authHeaders. Haga referencia a las siguientes secciones correspondientes para obtener más información sobre propiedades y ejemplos, respectivamente.	Sí
authHeaders	Otros encabezados de solicitud HTTP para la autenticación. Por ejemplo, para usar la autenticación de clave de API, puede seleccionar el tipo de autenticación como "Anónimo" y especificar la clave de API en el encabezado.	No
connectVia	Instancia de Integration Runtime que se usará para conectarse al almacén de datos. Obtenga más información en la sección Requisitos previos . Si no se especifica, esta propiedad se usará Azure Integration Runtime.	No

Para conocer los distintos tipos de autenticación, consulte las secciones correspondientes para ver los detalles.

• Autenticación básica
• Autenticación de la entidad de servicio
• Autenticación de credenciales de cliente de OAuth2
• Autenticación de identidad administrada asignada por el sistema
• Autenticación de identidad administrada asignada por el usuario
• Autenticación anónima

Uso de la autenticación básica

Establezca la propiedad authenticationType en Basic. Además de las propiedades genéricas descritas en las secciones anteriores, especifique las siguientes:

Propiedad	Descripción	Obligatorio
nombre de usuario	El nombre de usuario para acceder al punto de conexión REST.	Sí
contraseña	Contraseña del usuario (el valor userName ). Marque este campo como un tipo SecureString para almacenarlo de forma segura en Data Factory. También puede hacer referencia a un secreto almacenado en Azure Key Vault.	Sí

Ejemplo

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

Uso de la autenticación de entidad de servicio

Establezca la propiedad authenticationType en AadServicePrincipal. Además de las propiedades genéricas descritas en las secciones anteriores, especifique las siguientes:

Propiedad	Descripción	Obligatorio
servicePrincipalId	Especifique el ID de cliente de la aplicación Microsoft Entra.	Sí
servicePrincipalCredentialType	Especifique el tipo de credencial que se usará para la autenticación de entidad de servicio. Los valores permitidos son ServicePrincipalKey y ServicePrincipalCert.	No
Para ServicePrincipalKey
servicePrincipalKey	Especifique la clave de la aplicación Microsoft Entra. Marque este campo como SecureString para almacenarlo de forma segura en Data Factory o haga referencia a un secreto almacenado en Azure Key Vault.	No
Para ServicePrincipalCert
servicePrincipalEmbeddedCert	Especifique el certificado codificado en base64 de la aplicación registrada en el identificador de Entra de Microsoft y asegúrese de que el tipo de contenido del certificado es PKCS #12. Marque este campo como SecureString para almacenarlo de forma segura o hacer referencia a un secreto almacenado en Azure Key Vault. Vaya a esta sección para aprender a guardar el certificado en Azure Key Vault.	No
servicePrincipalEmbeddedCertPassword	Especifique la contraseña del certificado si el certificado está protegido por una. Marque este campo como SecureString para almacenarlo de forma segura o hacer referencia a un secreto almacenado en Azure Key Vault.	No
arrendatario	Especifique la información del inquilino (nombre de dominio o identificador de inquilino) en el que reside la aplicación. Para recuperarla, mantenga el puntero del mouse en la esquina superior derecha de Azure Portal.	Sí
aadResourceId	Especifique el recurso de Microsoft Entra que solicita autorización, por ejemplo, https://management.core.windows.net.	Sí
azureCloudType	Para la autenticación de la entidad de servicio, especifique el tipo de entorno de nube de Azure en el que está registrada la aplicación de Microsoft Entra. Los valores permitidos son AzurePublic, AzureChina, AzureUsGovernment y AzureGermany. De forma predeterminada, se usa el entorno de nube de la factoría de datos.	No

Ejemplo 1: uso de la autenticación de claves de entidad de servicio

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "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"
        }
    }
}

Ejemplo 2: uso de la autenticación de certificados de entidad de servicio

{
    "name": "RESTLinkedService",
    "properties": {
        "type": "RestService",
        "typeProperties": {
            "url": "<REST endpoint e.g. https://www.example.com/>",
            "authenticationType": "AadServicePrincipal",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": {
                "type": "SecureString",
                "value": "<the base64 encoded certificate of your application registered in Microsoft Entra ID>"
            },
            "servicePrincipalEmbeddedCertPassword": {
                "type": "SecureString",
                "value": "<password of your certificate>"
            },
            "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"
        }
    }
}

Guardar el certificado de entidad de servicio en Azure Key Vault

Tiene dos opciones para guardar el certificado de entidad de servicio en Azure Key Vault:

• Opción 1

  1. Convierta el certificado de entidad de servicio en una cadena base64. Obtenga más información en este artículo.

  2. Guarde la cadena base64 como un secreto en Azure Key Vault.

     

     

• Opción 2

  Si no puede descargar el certificado de Azure Key Vault, puede usar esta plantilla para guardar el certificado de entidad de servicio convertido como secreto en Azure Key Vault.

  

Uso de la autenticación de credenciales de cliente de OAuth2

Establezca la propiedad authenticationType en OAuth2ClientCredential. Además de las propiedades genéricas descritas en las secciones anteriores, especifique las siguientes:

Propiedad	Descripción	Obligatorio
tokenEndpoint	Punto de conexión de token del servidor de autorización para adquirir el token de acceso.	Sí
clientId	Identificador de cliente asociado a la aplicación.	Sí
secretoDelCliente	Secreto de cliente asociado a la aplicación. Marque este campo como un tipo SecureString para almacenarlo de forma segura en Data Factory. También puede hacer referencia a un secreto almacenado en Azure Key Vault.	Sí
scope	Ámbito del acceso necesario. Describe qué tipo de acceso se solicitará.	No
recurso	Servicio o recurso de destino al que se solicitará el acceso.	No

Ejemplo

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

Uso de la autenticación de identidad administrada asignada por el sistema

Establezca la propiedad authenticationType en ManagedServiceIdentity. Además de las propiedades genéricas descritas en las secciones anteriores, especifique las siguientes:

Propiedad	Descripción	Obligatorio
aadResourceId	Especifique el recurso de Microsoft Entra que solicita autorización, por ejemplo, https://management.core.windows.net.	Sí

Ejemplo

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

Uso de la autenticación de identidad administrada asignada por el usuario

Establezca la propiedad authenticationType en ManagedServiceIdentity. Además de las propiedades genéricas descritas en las secciones anteriores, especifique las siguientes:

Propiedad	Descripción	Obligatorio
aadResourceId	Especifique el recurso de Microsoft Entra que solicita autorización, por ejemplo, https://management.core.windows.net.	Sí
credenciales	Especifique la identidad administrada asignada por el usuario como objeto de credencial.	Sí

Ejemplo

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

Uso de los encabezados de autenticación

Además, puede configurar los encabezados de solicitud para realizar la autenticación, junto con los tipos de autenticación integrados.

Ejemplo: Uso de la autenticación de clave de 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"
        }
    }
}

Propiedades del conjunto de datos

En esta sección se proporciona una lista de las propiedades que admite el conjunto de datos de REST.

Para obtener una lista completa de secciones y propiedades que están disponibles para definir conjuntos de datos, consulte Conjuntos de datos y servicios vinculados.

Para copiar datos de REST, se admiten las siguientes propiedades:

Propiedad	Descripción	Obligatorio
tipo	La propiedad type del conjunto de datos debe establecerse en RestResource.	Sí
relativeUrl	Dirección URL relativa al recurso que contiene los datos. Cuando no se especifica la propiedad, solo se usa la dirección URL especificada en la definición del servicio vinculado. El conector HTTP copia los datos de la dirección URL combinada: [URL specified in linked service]/[relative URL specified in dataset].	No

Si estabas configurando requestMethod, additionalHeaders, requestBody y paginationRules en el conjunto de datos, todavía se admite as-is, mientras que se recomienda usar el nuevo modelo para las actividades hacia adelante.

Ejemplo:

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

Propiedades de la actividad de copia

En esta sección se proporciona una lista de las propiedades compatibles con REST como origen y receptor.

Para obtener una lista completa de las secciones y propiedades que están disponibles para definir actividades, consulte Canalizaciones.

REST como origen

Se admiten las siguientes propiedades en la sección source de la actividad de copia:

Propiedad	Descripción	Obligatorio
tipo	La propiedad type del origen de la actividad de copia debe establecerse en RestSource.	Sí
método de solicitud	Método HTTP. Los valores permitidos son GET (valor predeterminado) y POST.	No
additionalHeaders	Otros encabezados de solicitud HTTP.	No
requestBody	Cuerpo de la solicitud HTTP.	No
reglas de paginación	Las reglas de paginación para componer las solicitudes de página siguiente. Consulte la sección de soporte técnico de paginación sobre los detalles.	No
httpRequestTimeout	Tiempo de espera (el valor TimeSpan) de la solicitud HTTP para obtener una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no el tiempo de espera para leer los datos de respuesta. El valor predeterminado es 00:01:40.	No
requestInterval	El tiempo de espera antes de enviar la solicitud de página siguiente. El valor predeterminado es 00:00:01	No

Nota:

El conector REST omite cualquier encabezado "Accept" especificado en additionalHeaders. Puesto que solo admite respuestas JSON, el encabezado se establece automáticamente en Accept: application/json.
No se admite la paginación para las respuestas de la API REST en las que la estructura de nivel superior es una matriz JSON.

Ejemplo 1: Uso del método Get con paginación

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

Ejemplo 2: Uso del método 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 como receptor

Se admiten las siguientes propiedades en la sección sink de la actividad de copia:

Propiedad	Descripción	Obligatorio
tipo	La propiedad type del receptor de la actividad de copia debe establecerse en RestSink.	Sí
método de solicitud	Método HTTP. Los valores permitidos son POST (valor predeterminado), PUT y PATCH.	No
additionalHeaders	Otros encabezados de solicitud HTTP.	No
httpRequestTimeout	Tiempo de espera (el valor TimeSpan) de la solicitud HTTP para obtener una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no el tiempo de espera para escribir los datos. El valor predeterminado es 00:01:40.	No
requestInterval	El intervalo de tiempo entre diferentes solicitudes en milisegundos. El valor del intervalo de solicitudes debe ser un número entre [10, 60000].	No
httpCompressionType	Tipo de compresión HTTP que se va a usar al enviar datos con un nivel de compresión óptimo. Los valores permitidos son ninguno y gzip.	No
writeBatchSize	Número de registros que se van a escribir en el receptor de REST por lote. El valor predeterminado es 10000.	No

El conector de REST como receptor funciona con las API REST que aceptan JSON. Los datos se enviarán en JSON con el siguiente patrón. Según sea necesario, puede usar la asignación de esquemas de la actividad de copia para cambiar la forma de los datos de origen de modo que se ajusten a la carga esperada por la API de REST.

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

Ejemplo:

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

Propiedades de Asignación de instancias de Data Flow

REST se admite en flujos de datos de conjuntos de datos de integración y conjuntos de datos en línea.

Transformación de origen

Propiedad	Descripción	Obligatorio
método de solicitud	Método HTTP. Los valores permitidos son GET y POST.	Sí
relativeUrl	Dirección URL relativa al recurso que contiene los datos. Cuando no se especifica la propiedad, solo se usa la dirección URL especificada en la definición del servicio vinculado. El conector HTTP copia los datos de la dirección URL combinada: [URL specified in linked service]/[relative URL specified in dataset].	No
additionalHeaders	Otros encabezados de solicitud HTTP.	No
httpRequestTimeout	Tiempo de espera (el valor TimeSpan) de la solicitud HTTP para obtener una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no el tiempo de espera para escribir los datos. El valor predeterminado es 00:01:40.	No
requestInterval	El intervalo de tiempo entre diferentes solicitudes en milisegundos. El valor del intervalo de solicitudes debe ser un número entre [10, 60000].	No
QueryParameters.request_query_parameter O QueryParameters['request_query_parameter']	El usuario define "request_query_parameter", que hace referencia a un nombre de parámetro de consulta en la siguiente dirección URL de solicitud HTTP.	No

Transformación de receptor

Propiedad	Descripción	Obligatorio
additionalHeaders	Otros encabezados de solicitud HTTP.	No
httpRequestTimeout	Tiempo de espera (el valor TimeSpan) de la solicitud HTTP para obtener una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no el tiempo de espera para escribir los datos. El valor predeterminado es 00:01:40.	No
requestInterval	El intervalo de tiempo entre diferentes solicitudes en milisegundos. El valor del intervalo de solicitudes debe ser un número entre [10, 60000].	No
httpCompressionType	Tipo de compresión HTTP que se va a usar al enviar datos con un nivel de compresión óptimo. Los valores permitidos son ninguno y gzip.	No
writeBatchSize	Número de registros que se van a escribir en el receptor de REST por lote. El valor predeterminado es 10000.	No

Puede establecer los métodos delete, insert, update y upsert, así como los datos de fila relativos que se van a enviar al receptor REST para las operaciones CRUD.

Script de flujo de datos de ejemplo

Tenga en cuenta el uso de una transformación de alteración de fila antes del receptor para indicarle a ADF qué tipo de acción tomar con su receptor REST. Es decir, insertar, actualizar, upsert, eliminar.

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

Nota:

Data Flow genera un total de llamadas API de N+1 al procesar N páginas. Esto incluye una llamada inicial para deducir el esquema, seguida de N llamadas correspondientes al número de páginas capturadas desde el origen.

Compatibilidad con la paginación

Al copiar datos de las API de REST, por lo general, la API de REST limita su tamaño de carga de respuesta de una única solicitud a un número razonable; mientras que, para devolver una gran cantidad de datos, divide el resultado en varias páginas y exige que los autores de la llamada envíen solicitudes consecutivas para obtener la página siguiente del resultado. Por lo general, la solicitud para una página es dinámica y está compuesta por la información devuelta de la respuesta de página anterior.

Este conector REST genérico admite los siguientes patrones de paginación:

• Dirección URL absoluta o relativa de la siguiente solicitud = valor de propiedad en el cuerpo de la respuesta actual
• Dirección URL absoluta o relativa de la siguiente solicitud = valor de encabezado en los encabezados de la respuesta actual
• Parámetro de consulta de la siguiente solicitud = valor de propiedad en el cuerpo de la respuesta actual
• Parámetro de consulta de la siguiente solicitud = valor de encabezado en los encabezados de la respuesta actual
• Encabezado de la siguiente solicitud = valor de propiedad en el cuerpo de la respuesta actual
• Encabezado de la siguiente solicitud = valor de encabezado en los encabezados de la respuesta actual

Las reglas de paginación se definen como un diccionario en el conjunto de datos que contiene uno o más pares clave-valor que distinguen mayúsculas de minúsculas. La configuración se usará para generar la solicitud a partir de la segunda página. El conector detendrá la iteración cuando obtenga el código de estado HTTP 204 (sin contenido) o cualquiera de las expresiones JSONPath en "paginationRules" devuelva NULL.

Claves admitidas en reglas de paginación:

Clave	Descripción
AbsoluteUrl	Indica la dirección URL para emitir la siguiente solicitud. Puede ser una dirección URL absoluta o una dirección URL relativa.
QueryParameters.request_query_parameter O QueryParameters['request_query_parameter']	El usuario define "request_query_parameter", que hace referencia a un nombre de parámetro de consulta en la siguiente dirección URL de solicitud HTTP.
Headers.request_header O Headers['request_header']	El usuario define "request_header", que hace referencia a un nombre de encabezado en la siguiente solicitud HTTP.
CondiciónFinal:end_condition	"end_condition" la define el usuario, e indica la condición que hará finalizar el bucle de paginación en la siguiente solicitud HTTP.
NúmeroMáximoDeSolicitudes	Indica el número máximo de solicitudes de paginación. Si lo deja vacío significa que no hay límite.
SupportRFC5988	De forma predeterminada, se establece en true si no se define ninguna regla de paginación. Puede deshabilitar esta regla estableciendo supportRFC5988 en false o quitando esta propiedad del script.

Valores admitidos en reglas de paginación:

Importancia	Descripción
Headers.response_header O Headers['response_header']	El usuario define "response_header", que hace referencia a un nombre de encabezado en la respuesta HTTP actual, el valor que se usará para emitir la solicitud siguiente.
Una expresión JSONPath que empieza por "$" (que representa la raíz del cuerpo de respuesta)	El cuerpo de la respuesta debe contener solo un objeto JSON y la matriz del objeto, ya que no se admite el cuerpo de la respuesta. La expresión JSONPath debe devolver un único valor primitivo, que se usará para emitir la solicitud siguiente.

Nota:

Las reglas de paginación de los flujos de datos de asignación son diferentes de las de la actividad de copia en los aspectos siguientes:

1. El intervalo no se admite en los flujos de datos de asignación.
2. [''] no se admite en los flujos de datos de asignación. En su lugar, use {} para incluir el carácter especial en el escape. Por ejemplo, body.{@odata.nextLink}, cuyo nodo JSON @odata.nextLink contiene el carácter especial ..
3. La condición final se admite en los flujos de datos de asignación, pero la sintaxis de la condición es diferente de ella en la actividad de copia. body se usa para indicar el cuerpo de la respuesta en lugar de $. header se usa para indicar el encabezado de respuesta en lugar de headers. Estos son dos ejemplos que muestran esta diferencia:
   • Ejemplo 1:
     Actividad de copia: "EndCondition:$.data": "Empty"
     Flujos de datos de asignación: "EndCondition:body.data": "Empty"
   • Ejemplo 2:
     Actividad de copia: "EndCondition:headers.complete": "Exist"
     Flujos de datos de asignación: "EndCondition:header.complete": "Exist"

Ejemplos de reglas de paginación

En esta sección se proporciona una lista de ejemplos para la configuración de reglas de paginación.

Ejemplo 1: Variables en QueryParameters

En este ejemplo se proporcionan los pasos de configuración para enviar varias solicitudes cuyas variables se encuentran en QueryParameters.

Varias solicitudes:

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

Paso 1: Entrada sysparm_offset={offset} en dirección URL base o dirección URL relativa , como se muestra en las capturas de pantalla siguientes:

or

Paso 2: Establecer reglas de paginación como opción 1 o opción 2:

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

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

Ejemplo 2:Variables en AbsoluteUrl

En este ejemplo se proporcionan los pasos de configuración para enviar varias solicitudes cuyas variables se encuentran en AbsoluteUrl.

Varias solicitudes:

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

Paso 1: Introduzca {id} ya sea en URL base en la página de configuración del servicio vinculado o en URL relativa en el panel de conexión del conjunto de datos.

or

Paso 2: Establecer reglas de paginación como "AbsoluteUrl.{ id}" :"RANGE:1:100:1".

Ejemplo 3: Variables en encabezados

En este ejemplo se proporcionan los pasos de configuración para enviar varias solicitudes cuyas variables se encuentran en encabezados.

Varias solicitudes:

RequestUrl: https://example/table
Request 1: Header(id->0)
Request 2: Header(id->10)
......
Request 100: Header(id->100)

Paso 1: Introducir {id} dentro de Encabezados adicionales.

Paso 2: Establecer reglas de paginación como "Encabezados.{ id}" : "RANGE:0:100:10".

Ejemplo 4:Las variables se encuentran en AbsoluteUrl/QueryParameters/Headers, la variable final no está predefinida y la condición final se basa en la respuesta.

En este ejemplo se proporcionan pasos de configuración para enviar varias solicitudes cuyas variables están en AbsoluteUrl/QueryParameters/Headers, pero la variable final no está definida. Para respuestas diferentes, se muestra una configuración de regla de condición final diferente en el ejemplo 4.1-4.6.

Varias solicitudes:

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,
...... 

Dos respuestas encontradas en este ejemplo:

Respuesta 1:

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

Respuesta 2:

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

Paso 1: Establecer el intervalo de reglas de paginación como ejemplo 1 y dejar el final del intervalo vacío como "AbsoluteUrl.{ offset}": "RANGE:0::1000".

Paso 2: Establecer diferentes reglas de condición de finalización según las respuestas diferentes. Vea los siguientes ejemplos:

• Ejemplo 4.1: La paginación finaliza cuando el valor del nodo específico en respuesta está vacío

  La API REST devuelve la última respuesta en la estructura siguiente:

  {
      Data: []
  }
  

  Establezca la regla de condición de finalización como "EndCondition:$.data": "Empty" para finalizar la paginación cuando el valor del nodo específico en respuesta esté vacío.

  

• Ejemplo 4.2: La paginación finaliza cuando el valor del nodo específico en respuesta no existe

  La API REST devuelve la última respuesta en la estructura siguiente:

  {}
  

  Establezca la regla de condición de finalización como "EndCondition:$.data": "NonExist" para finalizar la paginación cuando el valor del nodo específico en respuesta no existe.

  

• Ejemplo 4.3: La paginación finaliza cuando existe el valor del nodo específico en respuesta

  La API REST devuelve la última respuesta en la estructura siguiente:

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

  Establezca la regla de condición de finalización como "EndCondition:$. Complete": "Exist" para finalizar la paginación cuando exista el valor del nodo específico en respuesta.

  

• Ejemplo 4.4: La paginación finaliza cuando el valor del nodo específico en respuesta es un valor const definido por el usuario

  La API REST devuelve la respuesta en la estructura siguiente:

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

  ......

  Y la última respuesta está en la estructura siguiente:

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

  Establezca la regla de condición de finalización como "EndCondition:$. Complete": "Const:true" para finalizar la paginación cuando el valor del nodo específico en respuesta es un valor const definido por el usuario.

  

• Ejemplo 4.5: La paginación finaliza cuando el valor de la clave de encabezado en respuesta es igual al valor const definido por el usuario

  Las claves de encabezado en las respuestas de la API REST se muestran en la estructura siguiente:

  Encabezado de respuesta 1: header(Complete->0)
  ......
  Encabezado de última respuesta: header(Complete->1)
  

  Establezca la regla de condición final como "EndCondition:headers. Complete": "Const:1" para finalizar la paginación cuando el valor de la clave de encabezado en respuesta es igual al valor const definido por el usuario.

  

• Ejemplo 4.6: La paginación finaliza cuando la clave existe en el encabezado de respuesta

  Las claves de encabezado en las respuestas de la API REST se muestran en la estructura siguiente:

  Encabezado de respuesta 1: header()
  ......
  Encabezado de última respuesta: header(CompleteTime->20220920)
  

  Establezca la regla de condición final como "EndCondition:headers. CompleteTime": "Exist" para finalizar la paginación cuando la clave existe en el encabezado de respuesta.

  

Ejemplo 5:Establecer la condición de finalización para evitar solicitudes infinitas cuando no se define la regla de intervalo

En este ejemplo se proporcionan los pasos de configuración para enviar varias solicitudes cuando no se usa la regla de intervalo. La condición final se puede establecer según el ejemplo 4.1-4.6 para evitar solicitudes infinitas. La API REST devuelve la respuesta en la estructura siguiente, en cuyo caso la dirección URL de la página siguiente se representa en 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="
    }
}
...

La última respuesta es:

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

Paso 1: Establezca reglas de paginación como "AbsoluteUrl": "$.paging.next".

Paso 2: Si next en la última respuesta siempre es el mismo con la última dirección URL de solicitud y no está vacía, se enviarán solicitudes infinitas. La condición final se puede usar para evitar solicitudes infinitas. Por lo tanto, para establecer la regla de condición final, consulte el ejemplo 4.1-4.6.

Ejemplo 6: Establezca el número máximo de solicitudes para evitar solicitudes infinitas.

Establezca MaxRequestNumber para evitar una solicitud infinita, como se muestra en la captura de pantalla siguiente:

Ejemplo 7: La regla de paginación RFC 5988 es compatible de forma predeterminada.

El back-end obtendrá automáticamente la siguiente dirección URL en función de los vínculos de estilo RFC 5988 del encabezado.

Sugerencia

Si no desea habilitar esta regla de paginación predeterminada, puede establecer supportRFC5988 en false o simplemente eliminarla en el script.

Ejemplo 8a: La siguiente dirección URL de solicitud del cuerpo de la respuesta cuando se utiliza la paginación en los flujos de datos de asignación

En este ejemplo se indica cómo establecer la regla de paginación y la regla de condición final en los flujos de datos de asignación cuando la siguiente dirección URL de solicitud es del cuerpo de la respuesta.

A continuación se muestra el esquema de respuesta:

Las reglas de paginación deben establecerse como la captura de pantalla siguiente:

De forma predeterminada, la paginación se detendrá cuando el cuerpo .{@odata.nextLink} sea nulo o esté vacío.

Pero si el valor de @odata.nextLink en el último cuerpo de respuesta es igual a la última dirección URL de solicitud, se producirá el bucle sin fin. Para evitar esta condición, defina reglas de condición final.

• Si Value en la última respuesta es Empty, la regla de condición final se puede establecer como se indica a continuación:

  

• Si el valor de la clave completa en el encabezado de respuesta es igual a true e indica el final de la paginación, la regla de la condición de finalización se puede establecer como se indica a continuación:

  

Ejemplo 8b: La siguiente dirección URL de solicitud del cuerpo de la respuesta cuando se utiliza la paginación en la actividad de copia

En este ejemplo se muestra cómo establecer la regla de paginación en una actividad de copia cuando la siguiente dirección URL de solicitud se encuentra dentro del cuerpo de la respuesta.

A continuación se muestra el esquema de respuesta:

Las reglas de paginación deben establecerse tal y como se muestra en la captura de pantalla siguiente:

Ejemplo 9: El formato de la respuesta es XML y la siguiente dirección URL de solicitud es del cuerpo de la respuesta cuando se utiliza la paginación en los flujos de datos de asignación.

En este ejemplo se indica cómo establecer la regla de paginación en los flujos de datos de asignación cuando el formato de respuesta es XML y la siguiente dirección URL de solicitud es del cuerpo de la respuesta. Como se muestra en la captura de pantalla siguiente, la primera dirección URL es https://< user.dfs.core.windows.NET/bugfix/test/movie_1.xml>

A continuación se muestra el esquema de respuesta:

La sintaxis de la regla de paginación es la misma que en el ejemplo 8 y debe establecerse como se indica a continuación en este ejemplo:

Exportación de la respuesta JSON tal cual

Puede usar el conector REST para exportar la respuesta JSON de una API REST as-is a varios sistemas de almacenamiento basados en archivos (receptores). Para habilitar este comportamiento de copia independiente del esquema, use la asignación de esquema predeterminada (no defina ninguna asignación en la pestaña Asignación de la actividad de copia).

Asignación de esquemas

Para copiar datos desde el punto de conexión de REST en un receptor tabular, vea asignación de esquemas.

Contenido relacionado

Para obtener una lista de los almacenes de datos que la actividad de copia admite como orígenes y receptores en Azure Data Factory, consulte Almacenes de datos y formatos admitidos.