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

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 Actividad de copia en Azure Data Factory, en el que se ofrece información general acerca de la actividad de copia.

Las diferencias entre este conector REST, el conector HTTP y el conector de tabla web son:

• El conector REST admite específicamente la copia de datos desde API de RESTful.
• El conector HTTP es genérico y puede recuperar datos desde cualquier punto de conexión HTTP, por ejemplo, para descargar archivos. 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 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)	① ②
Flujo de datos de asignación (origen/receptor)	①

① Azure Integration Runtime ② Entorno de ejecución de integración autohospedado

Para obtener una lista de los almacenes de datos que se admiten como orígenes y receptores, consulte la tabla de almacenes de datos admitidos.

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

• La copia de datos desde un punto de conexión de REST mediante los métodos GET o POST y la copia de datos hacia un punto de conexión de REST mediante los métodos POST, PUT o PATCH.
• Copia de datos mediante una de las siguientes autenticaciones: anónima, básica, entidad de servicio, credenciales de cliente OAuth2, identidad administrada asignada por el sistema e identidad administrada asignada por el usuario.
• Paginación en las API REST.
• En el caso de REST como origen, la copia de la respuesta JSON de REST tal cual o su análisis mediante la asignación de esquemas. Solo se admite la carga de respuesta en JSON.

Requisitos previos

Si el almacén de datos se encuentra en 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 que están 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 del entorno de ejecución de integración de red virtual administrada de Azure Data Factory para acceder a la red local sin instalar ni configurar un entorno de ejecución de integración autohospedado.

Consulte Estrategias de acceso a datos para más información sobre los mecanismos de seguridad de red y las opciones que admite Data Factory.

Introducción

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

• La herramienta Copiar datos
• Azure Portal
• El SDK de .NET
• El SDK de Python
• Azure PowerShell
• API REST
• La 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 nuevo 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
type	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)
authenticationType	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	Encabezados de solicitud HTTP adicionales para la autenticación. Por ejemplo, para usar la autenticación de clave de API, puede seleccionar el tipo de autenticación "Anónima" 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
userName	El nombre de usuario para acceder al punto de conexión REST.	Sí
password	Contraseña del usuario (valor userName). Marque este campo como de 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 bien para hacer 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 Microsoft Entra ID 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 bien haga 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 bien haga referencia a un secreto almacenado en Azure Key Vault.	No
tenant	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 para el 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. 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í
clientSecret	Secreto de cliente asociado a la aplicación. Marque este campo como de 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
resource	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 para el 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 para el que solicita autorización, por ejemplo, https://management.core.windows.net.	Sí
credentials	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 mediante 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 ver una lista completa de las secciones y propiedades 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
type	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 ha configurado requestMethod, additionalHeaders, requestBody y paginationRules en el conjunto de datos, todavía se admite tal cual, aunque se aconseja usar en el futuro el nuevo modelo en la actividad.

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 ver una lista completa de las secciones y propiedades que hay 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
type	La propiedad type del origen de la actividad de copia debe establecerse en RestSource.	Sí
requestMethod	Método HTTP. Los valores permitidos son GET (valor predeterminado) y POST.	No
additionalHeaders	Encabezados de solicitud HTTP adicionales.	No
requestBody	Cuerpo de la solicitud HTTP.	No
paginationRules	Las reglas de paginación para componer las solicitudes de página siguiente. Vea la sección Compatibilidad con la paginación para obtener más información.	No
httpRequestTimeout	El tiempo de espera (el valor TimeSpan) para que la solicitud HTTP obtenga una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no para leer los datos de la 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

Ejemplo 1: Mediante el método Get con la 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
type	La propiedad type del receptor de la actividad de copia debe establecerse en RestSink.	Sí
requestMethod	Método HTTP. Los valores permitidos son POST (valor predeterminado), PUT y PATCH.	No
additionalHeaders	Encabezados de solicitud HTTP adicionales.	No
httpRequestTimeout	El tiempo de espera (el valor TimeSpan) para que la solicitud HTTP obtenga una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no 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 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	Requerido
requestMethod	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	Encabezados de solicitud HTTP adicionales.	No
httpRequestTimeout	El tiempo de espera (el valor TimeSpan) para que la solicitud HTTP obtenga una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no 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	Requerido
additionalHeaders	Encabezados de solicitud HTTP adicionales.	No
httpRequestTimeout	El tiempo de espera (el valor TimeSpan) para que la solicitud HTTP obtenga una respuesta. Este valor es el tiempo de espera para obtener una respuesta, no 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

Observe el uso de una transformación alter row antes del receptor para indicar a ADF qué tipo de acción realizar con el receptor REST. Es decir, 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

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 las 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 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.
EndCondition: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.
MaxRequestNumber	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 las reglas de paginación:

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

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: Escriba sysparm_offset={offset} en URL base o URL relativa como se muestra en las siguientes capturas de pantalla:

or

Paso 2: Establezca las reglas de paginación como opción 1 u 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: Escriba {id} en la URL base en la página de configuración del servicio vinculado o la URL relativa en el panel de conexión del conjunto de datos.

or

Paso 2: Establezca las 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
Solicitud 1: Header(id->0)
Solicitud 2: Header(id->10)
......
Solicitud 100: Header(id->100)

Paso 1: Escriba {id} en los encabezados adicionales.

Paso 2: Establezca las reglas de paginación como "Headers.{id}" : "RANGE:0:100:10".

Ejemplo 4: Las variables están 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: Establezca el intervalo de reglas de paginación como el Ejemplo 1 y deje el final del intervalo vacío como "AbsoluteUrl.{offset}": "RANGE:0::1000".

Paso 2: Establezca distintas reglas de condición final según las últimas 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 final 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 final como "EndCondition:$.data": "NonExist" para finalizar la paginación cuando el valor del nodo específico en respuesta no exista.

  

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

  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 final como "EndCondition:$.Complete": "Exist" para finalizar la paginación cuando el valor del nodo específico en respuesta exista.

  

• 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 final como "EndCondition:$.Complete": "Const:true" para finalizar la paginación cuando el valor del nodo específico en respuesta sea 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 a un 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 sea 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 exista en el encabezado de respuesta.

  

Ejemplo 5: Establezca 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 use 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 siguiente estructura, en cuyo caso la dirección URL de la siguiente página 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 las reglas de paginación como "AbsoluteUrl": "$.paging.next".

Paso 2: Si next en la última respuesta es siempre igual a la última dirección URL de solicitud y no está vacía, se enviarán infinitas solicitudes. 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 solicitudes infinitas, 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.

Ejemplo 8: 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 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 body.{@odata.nextLink}** sea nulo o esté vacío.

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

• Si Valor en la última respuesta es Vacío, la regla de condición final puede establecerse 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 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 este conector REST para exportar la respuesta de JSON de la API REST tal cual a varios almacenes basados en archivos. Para lograr esa copia independiente del esquema, omita la sección “structure” (estructura, también denominada schema) en el conjunto de datos y la asignación de esquemas en 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 ver una lista de los almacenes de datos que la actividad de copia admite como orígenes y receptores en Azure Data Factory, consulte los Almacenes de datos y formatos que se admiten.