Activité Web dans Azure Data Factory et Azure Synapse Analytics

Article
09/25/2024

S’APPLIQUE À : Azure Data Factory Azure Synapse Analytics

Conseil

Essayez Data Factory dans Microsoft Fabric, une solution d’analyse tout-en-un pour les entreprises. Microsoft Fabric couvre tous les aspects, du déplacement des données à la science des données, en passant par l’analyse en temps réel, l’aide à la décision et la création de rapports. Découvrez comment démarrer un nouvel essai gratuitement !

L’activité Web peut être utilisée pour appeler un point de terminaison REST personnalisé à partir d’un pipeline Azure Data Factory ou Synapse. Vous pouvez transmettre des jeux de données et des services liés que l’activité peut utiliser et auxquels elle peut accéder.

Notes

L’activité web est également prise en charge pour appeler des URL hébergées sur un réseau virtuel privé en tirant parti du runtime d’intégration auto-hébergé. Le runtime d’intégration doit pouvoir visualiser le point de terminaison de l’URL.

Notes

La taille maximale de la charge utile de la réponse en sortie est de 4 Mo.

Créer une activité Web avec l’interface utilisateur

Pour utiliser une activité Web dans un pipeline, effectuez les étapes suivantes :

Recherchez Web dans le volet Activités de pipeline, puis faites glisser une activité Web vers le canevas du pipeline.
Sélectionnez la nouvelle activité Web sur le canevas si elle ne l’est pas déjà, et son onglet Paramètres pour en modifier les détails.
Spécifiez une URL, qui peut être une chaîne d’URL littérale ou toute combinaison d’expressions dynamiques, de fonctions, de variables système ou de sorties d’autres activités. Fournissez d’autres détails à soumettre avec la demande.
Utilisez la sortie de l’activité comme entrée pour toute autre activité, et référencez la sortie le contenu dynamique n’est pris en charge dans l’activité de destination.

Syntaxe

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

Propriétés type

Propriété	Description	Valeurs autorisées	Obligatoire
name	Nom de l’activité web	String	Oui
type	Doit avoir la valeur WebActivity.	String	Oui
method	Méthode d’API REST pour le point de terminaison cible.	Chaîne. Types pris en charge : « GET », « POST », « PUT », « PATCH », « DELETE »	Oui
url	Point de terminaison cible et chemin d’accès	Chaîne (ou expression avec resultType de chaîne). Si elle ne reçoit pas de réponse du point de terminaison, l’activité expire à une minute avec une erreur. Vous pouvez augmenter le délai de réponse jusqu’à 10 minutes en mettant à jour la propriété httpRequestTimeout	Oui
httpRequestTimeout	Durée du délai d’expiration de la réponse	hh:mm:ss avec comme valeur maximale 00:10:00. Si elle n’est pas spécifiée explicitement, sa valeur par défaut est 00:01:00	No
headers	En-têtes envoyés à la demande. Par exemple, pour définir la langue et le type sur une requête : `"headers" : { "Accept-Language": "en-us", "Content-Type": "application/json" }`.	Chaîne (ou expression avec resultType de chaîne)	Non
body	Représente la charge utile envoyée au point de terminaison.	Chaîne (ou expression avec resultType de chaîne). Voir le schéma de la charge utile de demande dans la section Schéma de la charge utile.	Obligatoire pour les méthodes POST/PUT/PATCH. Facultatif pour la méthode DELETE.
Authentification	Méthode d’authentification utilisée pour appeler le point de terminaison. Les types pris en charge sont « De base, Certificat client, Identité managée affectée par le système, Identité managée affectée par l’utilisateur, Principal de service ». Pour plus d’informations, consultez la section Authentification. Si l’authentification n’est pas obligatoire, excluez cette propriété.	Chaîne (ou expression avec resultType de chaîne)	Non
turnOffAsync	Option permettant de désactiver l’appel de HTTP GET sur le champ d’emplacement dans l’en-tête de réponse d’une réponse HTTP 202. Si sa valeur est true, elle cesse d’appeler HTTP GET sur l’emplacement http donné dans l’en-tête de réponse. Si sa valeur est false, elle continue d’appeler HTTP GET sur l’emplacement donné dans les en-têtes de réponse HTTP.	Les valeurs autorisées sont false (par défaut) et true.	No
disableCertValidation	Supprime la validation de certificat côté serveur (non recommandé, sauf si vous vous connectez à un serveur approuvé qui n’utilise pas de certificat d’autorité de certification standard).	Les valeurs autorisées sont false (par défaut) et true.	Non
jeux de données	Liste des jeux de données transmis au point de terminaison.	Tableau de références de jeu de données. Peut être un tableau vide.	Oui
linkedServices	Liste des services liés transmise au point de terminaison.	Tableau des références de service lié. Peut être un tableau vide.	Oui
connectVia	Le runtime d’intégration à utiliser pour se connecter à la banque de données. Vous pouvez utiliser le runtime d’intégration Azure ou un runtime d’intégration auto-hébergé (si votre banque de données se trouve sur un réseau privé). Si cette propriété n’est pas spécifiée, le service utilise le runtime d’intégration Azure par défaut.	Référence du runtime d’intégration.	Non

Notes

Les points de terminaison REST que l’activité web appelle doivent retourner une réponse de type JSON. Si elle ne reçoit pas de réponse du point de terminaison, l’activité expire à 1 minute avec une erreur. Pour les points de terminaison qui prennent en charge le modèle de demande-réponse asynchrone, l’activité web continue de patienter sans délai d’attente (jusqu’à 7 jours) ou jusqu’à ce que les points de terminaison signalent l’achèvement du travail.

Le tableau suivant affiche la configuration requise pour le contenu JSON :

Type de valeur	Corps de la demande	Response body
Objet JSON	Prise en charge	Prise en charge
Tableau JSON	Prise en charge de (À l’heure actuelle, les tableaux JSON ne fonctionnent pas en raison d’un bogue. Un correctif est en cours.)	Non pris en charge
Valeur JSON	Prise en charge	Non pris en charge
Type non-JSON	Non pris en charge	Non pris en charge

Authentification

Voici les types d’authentification pris en charge dans l’activité web.

None

Si l’authentification n’est pas requise, n’incluez pas la propriété « authentication ».

De base

Spécifiez le nom d’utilisateur et le mot de passe à utiliser avec l’authentification de base.

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

Certificat client

Spécifiez le contenu encodé en Base64 d’un fichier PFX et le mot de passe.

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

Le certificat doit être un certificat x509. Pour la conversion en fichier PFX, vous pouvez utiliser votre utilitaire favori. Pour l’encodage en base 64, vous pouvez utiliser l’extrait de code PowerShell suivant.

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

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

Identité managée

Spécifiez l’URI de ressource pour lequel le jeton d’accès sera demandé à l’aide de l’identité managée pour l’instance de la fabrique de données ou de l’espace de travail Synapse. Pour appeler l’API Gestion des ressources Azure, utilisez https://management.azure.com/. Pour plus d’informations sur le fonctionnement des identités managées, consultez la page de vue d'ensemble des identités managées pour les ressources Azure.

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

Notes

Si la fabrique de données ou l’espace de travail Synapse est configuré avec un dépôt git, vous devez stocker vos informations d’identification dans Azure Key Vault pour utiliser l’authentification de base ou de certificat client. Le service ne stocke pas les mots de passe dans git.

Principal du service

Spécifiez l’ID de locataire, l’ID du principal de service et la clé du principal de service à l’aide d’une chaîne sécurisée pour la clé secrète client.

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

Schéma de charge utile de demande

Lorsque vous utilisez la méthode POST/PUT, la propriété body représente la charge utile envoyée au point de terminaison. Vous pouvez transmettre des services liés et des jeux de données dans la charge utile. Voici le schéma de la charge utile :

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

Exemple

Dans cet exemple, l’activité web dans le pipeline appelle un point de terminaison REST. Elle transmet un service lié Azure SQL et un jeu de données Azure SQL au point de terminaison. Le point de terminaison REST utilise la chaîne de connexion Azure SQL pour se connecter au serveur SQL logique et retourne le nom de l’instance du serveur SQL.

Définition de pipeline

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

Valeurs de paramètre de pipeline

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

Code de point de terminaison de service 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);
}

Consultez d’autres activités de flux de contrôle prises en charge :

Partage via

Activité Web dans Azure Data Factory et Azure Synapse Analytics

Créer une activité Web avec l’interface utilisateur

Syntaxe

Propriétés type

Authentification

None

De base

Certificat client

Identité managée

Principal du service

Schéma de charge utile de demande

Exemple

Définition de pipeline

Valeurs de paramètre de pipeline

Code de point de terminaison de service web

Commentaires

Ressources supplémentaires

Partage via

Activité Web dans Azure Data Factory et Azure Synapse Analytics

Créer une activité Web avec l’interface utilisateur

Syntaxe

Propriétés type

Authentification

None

De base

Certificat client

Identité managée

Principal du service

Schéma de charge utile de demande

Exemple

Définition de pipeline

Valeurs de paramètre de pipeline

Code de point de terminaison de service web

Contenu connexe

Commentaires

Ressources supplémentaires