Actividad web en Azure Data Factory y Azure Synapse Analytics

Artículo
09/25/2024

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. Obtenga información sobre cómo iniciar una nueva evaluación gratuita.

La actividad web puede usarse para llamar a un punto de conexión REST personalizado desde una canalización de Azure Data Factory o Synapse. Puede pasar conjuntos de datos y servicios vinculados que la actividad consumirá y a los que tendrá acceso.

Nota

Se admite la actividad web para invocar direcciones URL que se hospedan en una red virtual privada y mediante el uso de un entorno de ejecución de integración autohospedado. El entorno de ejecución de integración debe tener una línea de visión al punto de conexión de la dirección URL.

Nota

El tamaño máximo de la carga de respuesta de salida admitido es de 4 MB.

Creación de una actividad web con la interfaz de usuario

Para usar una actividad web en una canalización, complete los pasos siguientes:

Busque web en el panel Actividades de canalización y arrastre una actividad web al lienzo de canalización.
Seleccione la nueva actividad web en el lienzo si aún no está seleccionada y su pestaña Configuración para editar sus detalles.
Especifique una dirección URL, que puede ser una cadena URL literal o cualquier combinación de expresiones y funciones dinámicas, variables del sistema o salidas de otras actividades. Proporcione otros detalles que se enviarán con la solicitud.
Use la salida de la actividad como entrada a cualquier otra actividad y haga referencia a la salida en cualquier lugar en el que se admita contenido dinámico en la actividad de destino.

Sintaxis

{
   "name":"MyWebActivity",
   "type":"WebActivity",
   "typeProperties":{
      "method":"Post",
      "url":"<URLEndpoint>",
      "httpRequestTimeout": "00:01:00"
      "connectVia": {
          "referenceName": "<integrationRuntimeName>",
          "type": "IntegrationRuntimeReference"
      }
      "headers":{
         "Content-Type":"application/json"
      },
      "authentication":{
         "type":"ClientCertificate",
         "pfx":"****",
         "password":"****"
      },
      "datasets":[
         {
            "referenceName":"<ConsumedDatasetName>",
            "type":"DatasetReference",
            "parameters":{
               ...
            }
         }
      ],
      "linkedServices":[
         {
            "referenceName":"<ConsumedLinkedServiceName>",
            "type":"LinkedServiceReference"
         }
      ]
   }
}

Propiedades de tipo

Propiedad	Descripción	Valores permitidos	Obligatorio
name	Nombre de la actividad web	String	Sí
type	Se debe establecer en WebActivity.	String	Sí
method	Método de API REST para el punto de conexión de destino.	String. Tipos admitidos: "GET", "POST", "PUT", "PATCH", "DELETE"	Sí
url	Punto de conexión y ruta de acceso de destino	Cadena (o expresión con un valor resultType de cadena). La actividad agotará el tiempo de espera en 1 minuto con un error si no recibe una respuesta del punto de conexión. Si actualiza el valor de la propiedad httpRequestTimeout, podrá aumentar este tiempo de espera de respuesta hasta los 10 minutos	Sí
httpRequestTimeout	Duración del tiempo de espera de respuesta	hh:mm:ss con un valor máximo de 00:10:00. Si el valor no se especifica explícitamente, se establecerá en 00:01:00 de forma predeterminada	No
headers	Encabezados que se envían a la solicitud. Por ejemplo, para establecer el idioma y el tipo en una solicitud: `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	Cadena (o expresión con un valor resultType de cadena)	No
body	Representa la carga útil que se envía al punto de conexión.	Cadena (o expresión con un valor resultType de cadena). Vea el esquema de la carga de solicitud en la sección Solicitar un esquema de carga.	Necesario para los métodos POST, PUT o PATCH . Opcional para el método DELETE.
autenticación	Método de autenticación usado para llamar al punto de conexión. Los tipos admitidos son "Básico, Certificado de cliente, Identidad gestionada asignada por el sistema, Identidad gestionada asignada por el usuario, Servicio principal". Para más información, consulte la sección Autenticación. Si la autenticación no es necesaria, excluya esta propiedad.	Cadena (o expresión con un valor resultType de cadena)	No
turnOffAsync	Opción para deshabilitar la invocación de HTTP GET en el campo de ubicación del encabezado de respuesta de una respuesta HTTP 202. Si se establece true, deja de invocar HTTP GET en la ubicación http especificada en el encabezado de respuesta. Si se establece false, continúa invocando la llamada HTTP GET en la ubicación especificada en los encabezados de respuesta http.	Los valores permitidos son false (valor predeterminado) y true.	No
disableCertValidation	Quita la validación del certificado del lado del servidor (no se recomienda a menos que se conecte a un servidor de confianza que no utilice un certificado CA estándar).	Los valores permitidos son false (valor predeterminado) y true.	No
conjuntos de datos	Lista de conjuntos de datos que se pasan al punto de conexión.	Matriz de referencias de conjunto de datos. Puede ser una matriz vacía.	Sí
linkedServices	Lista de servicios vinculados que se pasan al punto de conexión.	Matriz de referencias de servicios vinculados. Puede ser una matriz vacía.	Sí
connectVia	El entorno de ejecución de integración que se usará para conectarse al almacén de datos. Se puede usar Azure Integration Runtime o un entorno de ejecución de integración autohospedado (si el almacén de datos está en una red privada). Si no se especifica esta propiedad, el servicio usa el valor predeterminado de Azure Integration Runtime.	La referencia al entorno de ejecución de integración.	No

Nota

Los puntos de conexión REST que invoca la actividad web deben devolver una respuesta de tipo JSON. La actividad dará un error por tiempo de espera después de 1 minuto si no recibe una respuesta desde el punto de conexión. En el caso de los puntos de conexión que admiten el patrón de solicitud-respuesta asincrónico, la actividad web seguirá esperando sin que se agote el tiempo de espera (hasta 7 días) o hasta que los puntos de conexión señalen la finalización del trabajo.

En la tabla siguiente se enumeran los requisitos del contenido JSON:

Tipo de valor	Cuerpo de la solicitud	Response body
Objeto JSON	Compatible	Compatible
Matriz JSON	Se ha agregado compatibilidad con . (En la actualidad, las matrices JSON no funcionan como resultado un error. Hay una corrección en curso).	No compatible
Valor JSON	Compatible	No compatible
Tipo distinto de JSON	No compatible	No compatible

Authentication

A continuación, se muestran los tipos de autenticación admitidos en la actividad web.

None

Si la autenticación no es necesaria, no incluya la propiedad "authentication".

Básico

Especifique el nombre de usuario y la contraseña que se usarán con la autenticación básica.

"authentication":{
   "type":"Basic",
   "username":"****",
   "password":"****"
}

Certificado de cliente

Especifique un contenido codificado en base64 de un archivo PFX y la contraseña.

"authentication":{
   "type":"ClientCertificate",
   "pfx":"****",
   "password":"****"
}

El certificado debe ser un certificado x509. Para la conversión al archivo PFX, puede usar su utilidad favorita. Para la codificación base 64, puede usar el siguiente fragmento de código de PowerShell.

$fileContentBytes = get-content 'enr.dev.webactivity.pfx' -AsByteStream

[System.Convert]::ToBase64String($fileContentBytes) | Out-File ‘pfx-encoded-bytes.txt’

Identidad administrada

Especifique el URI de recurso para el que el token de acceso se solicitará utilizando la identidad administrada para la factoría de datos o la instancia del área de trabajo de Synapse. Para llamar a la API de Azure Resource Management, use https://management.azure.com/. Para más información sobre cómo funcionan las identidades administradas, consulte la página de información general Identidades administradas de recursos de Azure.

"authentication": {
	"type": "MSI",
	"resource": "https://management.azure.com/"
}

Nota

Si la factoría de datos o el área de trabajo de Synapse está configurada con un repositorio de Git, tiene que almacenar sus credenciales en Azure Key Vault para usar la autenticación básica o de certificado de cliente. El servicio no almacena contraseñas en Git.

Entidad de servicio

Especifique el identificador de inquilino, el identificador de entidad de servicio y la clave de entidad de servicio, mediante una cadena segura para el secreto de cliente.

"authentication": {
            "type": "ServicePrincipal",
            "tenant": "your_tenant_id",
            "servicePrincipalId": "your_client_id",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "your_client_secret"
            },
            "resource": "https://management.azure.com/"
}

Solicitar un esquema de carga

Al usar el método POST o PUT, la propiedad body representa la carga que se envía al punto de conexión. Puede pasar servicios vinculados y conjuntos de datos como parte de la carga. Este es el esquema de la carga:

{
    "body": {
        "myMessage": "Sample",
        "datasets": [{
            "name": "MyDataset1",
            "properties": {
                ...
            }
        }],
        "linkedServices": [{
            "name": "MyStorageLinkedService1",
            "properties": {
                ...
            }
        }]
    }
}

Ejemplo

En este ejemplo, la actividad web de la canalización llama a un punto de conexión REST. Pasa un servicio vinculado de Azure SQL y un conjunto de datos de Azure SQL al punto de conexión. El punto de conexión REST usa la cadena de conexión de Azure SQL para conectarse al servidor SQL lógico y devuelve el nombre de la instancia de SQL Server.

Definición de la canalización

{
    "name": "<MyWebActivityPipeline>",
    "properties": {
        "activities": [
            {
                "name": "<MyWebActivity>",
                "type": "WebActivity",
                "typeProperties": {
                    "method": "Post",
                    "url": "@pipeline().parameters.url",
                    "headers": {
                        "Content-Type": "application/json"
                    },
                    "authentication": {
                        "type": "ClientCertificate",
                        "pfx": "*****",
                        "password": "*****"
                    },
                    "datasets": [
                        {
                            "referenceName": "MySQLDataset",
                            "type": "DatasetReference",
                            "parameters": {
                                "SqlTableName": "@pipeline().parameters.sqlTableName"
                            }
                        }
                    ],
                    "linkedServices": [
                        {
                            "referenceName": "SqlLinkedService",
                            "type": "LinkedServiceReference"
                        }
                    ]
                }
            }
        ],
        "parameters": {
            "sqlTableName": {
                "type": "String"
            },
            "url": {
                "type": "String"
            }
        }
    }
}

Valores de parámetro de canalización

{
    "sqlTableName": "department",
    "url": "https://adftes.azurewebsites.net/api/execute/running"
}

Código de punto de conexión del servicio web


[HttpPost]
public HttpResponseMessage Execute(JObject payload)
{
    Trace.TraceInformation("Start Execute");

    JObject result = new JObject();
    result.Add("status", "complete");

    JArray datasets = payload.GetValue("datasets") as JArray;
    result.Add("sinktable", datasets[0]["properties"]["typeProperties"]["tableName"].ToString());

    JArray linkedServices = payload.GetValue("linkedServices") as JArray;
    string connString = linkedServices[0]["properties"]["typeProperties"]["connectionString"].ToString();

    System.Data.SqlClient.SqlConnection sqlConn = new System.Data.SqlClient.SqlConnection(connString);

    result.Add("sinkServer", sqlConn.DataSource);

    Trace.TraceInformation("Stop Execute");

    return this.Request.CreateResponse(HttpStatusCode.OK, result);
}

Vea otras actividades de flujo de control admitidas:

Compartir vía

Actividad web en Azure Data Factory y Azure Synapse Analytics

Creación de una actividad web con la interfaz de usuario

Sintaxis

Propiedades de tipo

Authentication

None

Básico

Certificado de cliente

Identidad administrada

Entidad de servicio

Solicitar un esquema de carga

Ejemplo

Definición de la canalización

Valores de parámetro de canalización

Código de punto de conexión del servicio web

Comentarios

Recursos adicionales

Compartir vía

Actividad web en Azure Data Factory y Azure Synapse Analytics

Creación de una actividad web con la interfaz de usuario

Sintaxis

Propiedades de tipo

Authentication

None

Básico

Certificado de cliente

Identidad administrada

Entidad de servicio

Solicitar un esquema de carga

Ejemplo

Definición de la canalización

Valores de parámetro de canalización

Código de punto de conexión del servicio web

Contenido relacionado

Comentarios

Recursos adicionales