Activité de script dans Data Factory et Azure Synapse Analytics

Dans cet article, vous allez apprendre à créer une activité de script dans Azure Data Factory pour exécuter des requêtes PostgreSQL personnalisées. Avec l’activité de script, vous pouvez exécuter différents types de commandes PostgreSQL, telles que DML (Data Manipulation Language) et DDL (Data Definition Language), directement dans vos pipelines.

Instructions DML :INSERT, UPDATE, DELETE et SELECT

Instructions DDL :CREATE, ALTER et DROP

Prerequisites

• Une instance de serveur flexible Azure Database pour PostgreSQL. Pour plus d’informations, consultez Créer une base de données Azure pour PostgreSQL.
• (Facultatif) Runtime d’intégration Azure créé dans un réseau virtuel managé.
• Un service lié Azure Data Factory connecté à Azure Database pour PostgreSQL.

Créer une activité de script

1. Dans Azure Data Factory Studio, sélectionnez le hub Auteur . Pointez sur la section Pipelines , sélectionnez ... à gauche, puis sélectionnez Nouveau pipeline pour créer un pipeline.

   

   

2. Sous Général, faites glisser et déposez l’activité de script dans le pipeline.

   

   1. Sous l’onglet Général , donnez un nom à votre activité de script.

   

3. Basculez vers l’onglet Paramètres et sélectionnez votre service lié Azure Database pour PostgreSQL, ou créez-en un. Une fois ajoutée, sélectionnez Tester la connexion pour vérifier que votre connexion est valide.

   

4. Sélectionnez l’option Requête ou NonQuery en fonction de votre script.

   L’activité de script prend en charge les instructions de type requête et non-requête.

   

   Query

   Les instructions de requête exécutent des instructions PostgreSQL qui retournent des résultats. Souvent des instructions SELECT. Une instruction Query retourne des enregistrements de données.

   

   Exemple de charge de données avec une requête.

   {
       "name": "Sample of select statement",
       "type": "Script",
       "dependsOn": [],
       "policy": {
           "timeout": "1.12:00:00",
           "retry": 0,
           "retryIntervalInSeconds": 30,
           "secureOutput": false,
           "secureInput": false
       },
       "userProperties": [],
       "linkedServiceName": {
           "referenceName": "AzurePostgreSQL",
           "type": "LinkedServiceReference"
       },
       "typeProperties": {
           "scripts": [
               {
                   "type": "Query",
                   "text": "SELECT * FROM sample_table WHERE sample_int = 100; "
               }
           ],
           "scriptBlockExecutionTimeout": "02:00:00"
       }
   }
   

   Non-Requête

   Les instructions non-Query exécutent des instructions PostgreSQL qui ne retournent aucun résultat. Souvent des instructions INSERT, UPDATE ou DELETE. Retourne le nombre de lignes affectées.

   

   Exemple de charge utile avec une requête non-requête.

   {
       "name": "Sample of drop statements",
       "type": "Script",
       "dependsOn": [],
       "policy": {
           "timeout": "1.12:00:00",
           "retry": 0,
           "retryIntervalInSeconds": 30,
           "secureOutput": false,
           "secureInput": false
       },
       "userProperties": [],
       "linkedServiceName": {
           "referenceName": "AzurePostgreSQL1",
           "type": "LinkedServiceReference"
       },
       "typeProperties": {
           "scripts": [
               {
                   "type": "NonQuery",
                   "text": "DROP TABLE IF EXISTS sample_table; "
               }
           ],
           "scriptBlockExecutionTimeout": "02:00:00"
       }
   }
   

Créer plusieurs scripts à l’intérieur d’une activité de script

Vous pouvez inclure plusieurs requêtes dans une activité de script en sélectionnant le + signe à côté de Script pour ajouter un nouvel input de script.

Vous pouvez supprimer des zones d’entrée de requête en utilisant l’icône supprimer à côté de Script.

Voici un exemple de charge utile avec deux requêtes distinctes.

{
      "name": "Sample of multiple select statements",
      "type": "Script",
      "dependsOn": [],
      "policy": {
         "timeout": "1.12:00:00",
         "retry": 0,
         "retryIntervalInSeconds": 30,
         "secureOutput": false,
         "secureInput": false
      },
      "userProperties": [],
      "linkedServiceName": {
         "referenceName": "AzurePostgreSQL1",
         "type": "LinkedServiceReference"
      },
      "typeProperties": {
         "scripts": [
            {
                  "type": "Query",
                  "text": "SELECT * FROM sample_table WHERE sample_int = 100; "
            },
            {
                  "type": "Query",
                  "text": "SELECT * FROM sample_table WHERE sample_int > 250; "
            }
         ],
         "scriptBlockExecutionTimeout": "02:00:00"
      }
}

Paramètres de script

Important

Les instructions à plusieurs requêtes utilisant des paramètres de sortie ne sont pas prises en charge. Fractionnez toutes les requêtes de sortie en blocs de script distincts au sein de la même activité de script ou d’une activité de script différente.

L’activité de script prend en charge deux types de paramètres de script : les paramètres positionnels et nommés. Les paramètres nommés utilisent le nom des paramètres et sont spécifiés comme @<name> dans les requêtes. Les paramètres positionnels utilisent l’index des paramètres et sont spécifiés dans la requête dans l’ordre comme $<position number> avec un index de départ de 1.

Paramètres nommés (recommandé)

Les paramètres nommés utilisent un @ préfixe pour le nom du paramètre. Définissez les paramètres nommés en tant que paramètres de sortie en définissant la valeur sur Null avec la case Traiter comme null activée dans l’interface utilisateur, et avec la charge utile laissée vide ou null. La valeur du texte doit être null.

Le nom défini dans la procédure de sortie est le nom utilisé dans la sortie de données resultSets . Le nom défini dans la ligne de sortie de l’interface utilisateur est utilisé pour le nom de outputParameters.

Exemple de résultat de l’exécution de l’interface utilisateur

"resultSetCount": 1,
"recordsAffected": 0,
"resultSets": [
   {
      "rowCount": 1,
      "rows": [
         {
            "output1": 10,
            "output2": "\"Hello World\""
         }
      ]
   }
],
"outputParameters": {
   "output10": 10,
   "output20": "\"Hello World\""
}

Exemple de charge utile pour le paramètre de sortie.

"scripts": [
  {
    "text": "CREATE OR REPLACE PROCEDURE swap_proc (input1 IN TEXT, input2 IN BIGINT, output1 OUT BIGINT, output2 OUT TEXT) LANGUAGE plpgsql AS $$ DECLARE BEGIN output2 := input1; output1 := input2; END $$",
    "type": "NonQuery"
  },
  {
    "text": "CALL swap_proc(@input1, @input2, null, null)",
    "type": "Query",
    "parameters": [
      {
        "name": "input1",
        "type": "String",
        "value": "Hello world",
        "direction": "Input",
        "size": 100
      },
      {
        "name": "input2",
        "type": "INT32",
        "value": 1234,
        "direction": "Input"
      },
      {
        "name": "output1",
        "type": "INT32",
        "direction": "Output"
      },
      {
        "name": "output2",
        "type": "String",
        "direction": "Output",
        "size": 100
      }
    ]
  }
]

Paramètres positionnels

Important

Les instructions multi-requêtes utilisant des paramètres positionnels ne sont pas prises en charge. Vérifiez que toutes les requêtes avec des paramètres positionnels se trouvent dans des blocs de script distincts au sein de la même activité de script ou d’une activité de script différente.

Pour utiliser des paramètres positionnels, utilisez un espace réservé $<positional number> dans votre requête. Sous les paramètres, le name champ doit être laissé vide dans l’interface utilisateur et spécifié comme null dans la charge utile.

"scripts": [
   {
      "text": "SELECT * FROM customers WHERE first_name = $1 AND age = $2;",
      "type": "Query",
      "parameters": [
        {
          "name": null,
          "type": "String",
          "value": "John",
          "direction": "Input",
          "size": 256
        },
        {
          "name": null,
          "type": "INT32",
          "value": 52,
          "direction": "Input"
        }
      ]
   }
]

Exemple de paramètre positionnel valide

"scripts": [
   {
      "text": "SELECT * FROM customers WHERE first_name = $1;",
      "type": "Query",
      "parameters": [
        {
          "name": null,
          "type": "String",
          "value": "John",
          "direction": "Input",
          "size": 256
        }
      ]
   },
   {
      "text": "SELECT * FROM customers WHERE age = $2;",
      "type": "Query",
      "parameters": [
        {
          "name": null,
          "type": "INT32",
          "value": 52,
          "direction": "Input"
        }
      ]
   }
]

Exemple de paramètre positionnel non valide

"scripts": [
   {
      "text": "SELECT * FROM customers WHERE first_name = $1; SELECT * FROM customers WHERE age = $2;",
      "type": "Query",
      "parameters": [
        {
          "name": null,
          "type": "String",
          "value": "John",
          "direction": "Input",
          "size": 256
        },
        {
          "name": null,
          "type": "INT32",
          "value": 52,
          "direction": "Input"
        }
      ]
   }
]

Paramètres avancés

Les paramètres avancés dans l’activité de script d’Azure Data Factory pour PostgreSQL vous permettent d’affiner les options d’exécution et de journalisation de vos flux de travail de données. Vous pouvez définir des délais d’expiration de bloc de script pour empêcher les requêtes longues d’affecter la fiabilité du pipeline et activer la journalisation détaillée pour suivre les notifications PostgreSQL et les sorties d’activité. Ces fonctionnalités vous aident à maintenir les opérations de données fortes et vous donnent plus de visibilité sur vos exécutions de pipeline dans Azure.

Délai d’expiration de l’exécution du bloc de script

Définissez un délai d’expiration en minutes pour chaque exécution de bloc de script. Si un bloc de script dans votre activité de script passe au fil du délai d’attente, l’activité entière échoue.

   "typeProperties": {
      "scripts": [
         {
               "type": "Query",
               "text": "SELECT pg_sleep(40);"
         },
         {
               "type": "Query",
               "text": "SELECT pg_sleep(40);"
         },
         {
               "type": "Query",
               "text": "SELECT pg_sleep(40);"
         }
      ],
      "scriptBlockExecutionTimeout": "00:01:00"
   }

Logging

Utilisez la journalisation pour envoyer des avis PostgreSQL à un stockage Blob externe ou à un stockage interne.

Stockage externe

Pour la journalisation externe, ouvrez l’onglet Avancé , puis sélectionnez Activer la journalisation et le stockage externe. Ajoutez un compte de stockage Blob en créant un nouveau service lié pour votre compte de stockage Blob. Vous pouvez éventuellement entrer un chemin d’accès au dossier. Si vous le laissez vide, les fichiers journaux seront placés dans le dossier scriptactivity-logs.

"typeProperties": {
   "scripts": [
      {
         "type": "Query",
         "text": "DO $$ BEGIN RAISE Notice 'Hello'; RAISE Notice 'World!'; END $$;"
      }
   ],
   "scriptBlockExecutionTimeout": "02:00:00",
   "logSettings": {
      "logDestination": "ExternalStore",
      "logLocationSettings": {
         "linkedServiceName": {
            "referenceName": "<Azure Blob Storage linked service name>",
            "type": "LinkedServiceReference"
         },
         "path": "<Azure Blob Storage folder path>"
      }
   }
}

Sortie de l’activité

Pour la journalisation des sorties d’activité, développez la section Avancé et sélectionnez Activer la journalisation et la sortie d’activité. Ces options activent la journalisation dans la sortie de l’activité.

"typeProperties": {
   "scripts": [
      {
         "type": "Query",
         "text": "DO $$ BEGIN RAISE Notice 'Hello'; RAISE Notice 'World!'; END $$;"
      }
   ],
   "scriptBlockExecutionTimeout": "02:00:00",
   "logSettings": {
      "logDestination": "ActivityOutput"
   }
}

Contenu connexe

• En savoir plus sur l’activité de script pour Azure Data Factory ou Synapse Analytics
• Activité de copie dans Azure Database pour PostgreSQL
• Comment se connecter au point de terminaison privé Data Factory
• Mise en réseau avec Private Link dans Azure Database pour PostgreSQL