API de framework d’extensibilité pour SQL Server

S’applique à : SQL Server 2019 (15.x) et versions ultérieures

Vous pouvez utiliser le framework d’extensibilité pour écrire des extensions de langage de programmation pour SQL Server. L’API Extensibility Framework pour SQL Server est une API qui peut être utilisée par une extension de langage pour interagir avec et échanger des données avec SQL Server.

En tant qu’auteur d’extension de langage, vous pouvez utiliser cette référence avec les extensions de langage open source afin de comprendre comment utiliser l’API pour écrire vos propres extensions de langage. Vous trouverez le code source de l’extension de langage sur aka.ms/mssql-lang-extensions.

Vous trouverez les informations de syntaxe et d’arguments sur toutes les fonctions d’API de cet article.

Valeur retournée

Toutes les fonctions retournent un SQLRETURN paramètre. Si la valeur est autre que SQL_SUCCESS, la valeur est traitée comme une erreur et l’exécution du script s’arrête.

Sortie standard

Toute sortie par l’extension aux flux de sortie ou d’erreur standard est tracée dans le fichier journal de la session et est finalement renvoyée à SQL Server. Cela est similaire à tout ce qui s’affiche dans l’onglet messages SQL Server Management Studio (SSMS).

Init

Cette fonction est appelée une seule fois et est utilisée pour initialiser le runtime en vue de l’exécution.

Syntaxe

SQLRETURN Init(
    SQLCHAR *ExtensionParams,
    SQLULEN ExtensionParamsLength,
    SQLCHAR *ExtensionPath,
    SQLULEN ExtensionPathLength,
    SQLCHAR *PublicLibraryPath,
    SQLULEN PublicLibraryPathLength,
    SQLCHAR *PrivateLibraryPath,
    SQLULEN PrivateLibraryPathLength
);

Arguments

Argument Entrée/sortie Description
ExtensionParams Input Chaîne terminée nulle contenant PARAMETERS la valeur fournie pendant CREATE EXTERNAL LANGUAGE ou ALTER EXTERNAL LANGUAGE
ExtensionParamsLength Input Longueur en octets de ExtensionParams (à l’exclusion du caractère d’arrêt Null)
ExtensionPath Input Chaîne UTF-8 terminée par null contenant le chemin absolu du répertoire d’installation de l’extension
ExtensionPathLength Input Longueur en octets de ExtensionPath (à l’exclusion du caractère d’arrêt Null)
PublicLibraryPath Input Chaîne UTF-8 terminée par null contenant le chemin absolu vers le répertoire des bibliothèques externes publiques pour ce langage externe
PublicLibraryPathLength Input Longueur en octets de PublicLibraryPath (à l’exclusion du caractère d’arrêt Null)
PrivateLibraryPath Input Chaîne UTF-8 terminée par null contenant le chemin absolu vers le répertoire des bibliothèques externes privées pour cet utilisateur et ce langage externe
PrivateLibraryPathLength Input Longueur en octets de PrivateLibraryPath (à l’exclusion du caractère d’arrêt Null)

InitSession

Cette fonction est appelée une fois par session et initialise des paramètres propres à la session.

Syntaxe

SQLRETURN InitSession(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLCHAR*        Script,
    SQLULEN         ScriptLength,
    SQLUSMALLINT    InputSchemaColumnsNumber,
    SQLUSMALLINT    ParametersNumber
    SQLCHAR*        InputDataName,
    SQLUSMALLINT    InputDataNameLength,
    SQLCHAR*        OutputDataName,
    SQLUSMALLINT    OutputDataNameLength
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête
Script Input Chaîne UTF-8 terminée par null contenant l’sp_execute_external_script @script
ScriptLength Input Longueur en octets de ScriptScript (à l’exclusion du caractère d’arrêt Null)
InputSchemaColumnsNumber Input Nombre de colonnes dans le jeu de résultats de @input_data_1sp_execute_external_script
ParametersNumber Input Nombre de paramètres d’entrée de @params sp_execute_external_script
InputDataName Input Chaîne UTF-8 terminée par null contenant l’sp_execute_external_script @input_data_1_name
InputDataNameLength Input Longueur en octets de InputDataName (à l’exclusion du caractère d’arrêt Null)
OutputDataName Input Chaîne UTF-8 terminée par null contenant l’sp_execute_external_script @output_data_1_name
OutputDataNameLength Input Longueur en octets de OutputDataName (à l’exclusion du caractère d’arrêt Null)

InitColumn

Initialiser les informations d’une colonne donnée pour une session particulière.

Cette fonction est appelée pour chaque colonne du jeu de résultats de @input_data_1 dans sp_execute_external_script.

La structure de colonne de ce jeu de résultats est appelée schéma d’entrée.

Syntaxe

SQLRETURN InitColumn(
    SQLGUID       SessionId,
    SQLUSMALLINT  TaskId,
    SQLUSMALLINT  ColumnNumber,
    SQLCHAR*      ColumnName,
    SQLSMALLINT   ColumnNameLength,
    SQLSMALLINT   DataType,
    SQLULEN       ColumnSize,
    SQLSMALLINT   DecimalDigits,
    SQLSMALLINT   Nullable,
    SQLSMALLINT   PartitionByNumber,
    SQLSMALLINT   OrderByNumber
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête
ColumnNumber Input Entier identifiant l’index de cette colonne dans le schéma d’entrée. Les colonnes sont numérotées séquentiellement dans l’ordre croissant à partir de 0
ColumnName Input Chaîne UTF-8 terminée par null contenant le nom de la colonne
ColumnNameLength Input Longueur en octets de ColumnName (à l’exclusion du caractère d’arrêt Null)
Data type Input Type ODBC C identifiant le type de données de cette colonne
ColumnSize Input Taille maximale en octets des données sous-jacentes de cette colonne.

Pour SQL_C_CHARles types de données et SQL_C_WCHARSQL_C_BINARY les types de données, les valeurs supérieures à 8 000 indiquent que cette colonne représente un objet métier, avec des tailles allant jusqu’à 2 Go
DecimalDigits Input Chiffres décimaux des données sous-jacentes de cette colonne, tels que définis par les chiffres décimaux
Nullable Input Valeur qui indique si cette colonne peut contenir des NULL valeurs. Valeurs possibles :

- SQL_NO_NULLS: la colonne ne peut pas contenir de NULL valeurs.
- SQL_NULLABLE: la colonne peut contenir des NULL valeurs
PartitionByNumber Input Valeur qui indique l’index de cette colonne dans la @input_data_1_partition_by_columns séquence dans sp_execute_external_script. Les colonnes sont numérotées séquentiellement dans l’ordre croissant à partir de 0. Si cette colonne n’est pas incluse dans la séquence, la valeur est -1
OrderByNumber Input Valeur qui indique l’index de cette colonne dans la @input_data_1_order_by_columns séquence dans sp_execute_external_script. Les colonnes sont numérotées séquentiellement dans l’ordre croissant à partir de 0. Si cette colonne n’est pas incluse dans la séquence, la valeur est -1

InitParam

Initialiser les informations relatives à un paramètre d’entrée donné pour une session particulière.

Cette fonction est appelée pour chaque paramètre de @params dans sp_execute_external_script.

Syntaxe

SQLRETURN InitParam(
    SQLGUID      SessionId,
    SQLUSMALLINT TaskId,
    SQLUSMALLINT ParamNumber,
    SQLCHAR*     ParamName,
    SQLSMALLINT  ParamNameLength,
    SQLSMALLINT  DataType,
    SQLULEN      ParamSize,
    SQLSMALLINT  DecimalDigits,
    SQLPOINTER   ParamValue,
    SQLINTEGER   StrLen_or_Ind,
    SQLSMALLINT  InputOutputType
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête
ParamNumber Input Entier identifiant l’index de ce paramètre. Les paramètres sont numérotés séquentiellement dans l’ordre croissant à partir de 0
ParamName Input Chaîne UTF-8 terminée par null contenant le nom du paramètre
ParamNameLength Input Longueur en octets de ParamName (à l’exclusion du caractère d’arrêt Null)
Data type Input Type ODBC C identifiant le type de données de ce paramètre
ParamSize Input Taille maximale en octets des données sous-jacentes de ce paramètre.

Pour SQL_C_CHARles types de données et SQL_C_WCHARSQL_C_BINARY les types de données, les valeurs supérieures à 8 000 indiquent que ce paramètre représente l’objet LOB et avec des tailles allant jusqu’à 2 Go
DecimalDigits Input Chiffres décimaux des données sous-jacentes dans ce paramètre, tels que définis par les chiffres décimaux
ParamValue Input Pointeur vers une mémoire tampon contenant la valeur du paramètre
StrLen_or_Ind Input Valeur entière indiquant la longueur en octets de ParamValue, ou SQL_NULL_DATA pour indiquer que les données sont NULL.

StrLen_or_Ind[col] peut être ignoré si une colonne n’est pas nullable et ne représente pas l’un des types de données suivants : SQL_C_CHAR, SQL_C_WCHAR et SQL_C_BINARY, SQL_C_NUMERIC ou SQL_C_TYPE_TIMESTAMP. Sinon, il pointe vers un tableau valide avec RowsNumber des éléments, où chaque élément contient sa longueur ou ses données d’indicateur Null
InputOutputType Input Type du paramètre . L’argument InputOutputType est l’une des valeurs suivantes :

- SQL_PARAM_INPUT
- SQL_PARAM_INPUT_OUTPUT

Execute

Exécuter le @script dans sp_execute_external_script.

Cette fonction peut être appelée plusieurs fois. une fois pour chaque flux de blocs et pour chaque partition du @input_data_1_partition_by_columns dans sp_execute_external_script.

Syntaxe

SQLRETURN Execute(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLULEN         RowsNumber,
    SQLPOINTER*     Data,
    SQLINTEGER**    StrLen_or_Ind,
    SQLUSMALLINT*   OutputSchemaColumnsNumber
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête
RowsNumber Input Nombre de lignes dans le Data
Data Input Tableau à deux dimensions qui contient le jeu de résultats de @input_data_1 sp_execute_external_script.

Le nombre total de colonnes est InputSchemaColumnsNumber celui qui a été reçu dans l’appel InitSession . Chaque colonne contient des RowsNumber éléments qui doivent être interprétés en fonction du type de colonne d’InitColumn.
Les éléments indiqués dans NULLStrLen_or_Ind ne sont pas garantis comme valides et doivent être ignorés
StrLen_or_Ind Input Tableau à deux dimensions qui contient l’indicateur length/NULL pour chaque valeur en Data. Valeurs possibles de chaque cellule :

- n, où n > 0. Indication de la longueur des données en octets
- SQL_NULL_DATA, indiquant une NULL valeur.
Le nombre total de colonnes est InputSchemaColumnsNumber celui qui a été reçu dans l’appel InitSession . Chaque colonne contient des RowsNumber éléments qui doivent être interprétés en fonction du type de colonne d’InitColumn.
StrLen_or_Ind[col] peut être ignoré, si une colonne n’est pas nullable et ne représente pas l’un des types de données suivants : SQL_C_CHAR, SQL_C_WCHAR et SQL_C_BINARY, SQL_C_NUMERIC ou SQL_C_TYPE_TIMESTAMP. Sinon, il pointe vers un tableau valide avec RowsNumber des éléments, chaque élément contient sa longueur ou ses données d’indicateur Null
OutputSchemaColumnsNumber Sortie Pointeur vers une mémoire tampon dans laquelle retourner le nombre de colonnes dans le jeu de résultats attendu de l’sp_execute_external_script @script

GetResultColumn

Récupérer les informations relatives à une colonne de sortie donnée pour une session particulière.

Cette fonction est appelée pour chaque colonne du jeu de résultats de @script dans sp_execute_external_script.

La structure de colonne de ce jeu de résultats est appelée schéma de sortie.

Syntaxe

SQLRETURN GetResultColumn(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLUSMALLINT    ColumnNumber,
    SQLSMALLINT*    DataType,
    SQLINTEGER*     ColumnSize,
    SQLSMALLINT*    DecimalDigits,
    SQLSMALLINT*    Nullable
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête
ColumnNumber Input Entier identifiant l’index de cette colonne dans le schéma de sortie. Les colonnes sont numérotées séquentiellement dans l’ordre croissant à partir de 0
Data type Sortie Pointeur vers la mémoire tampon qui contient le type ODBC C identifiant le type de données de cette colonne
ColumnSize Sortie Pointeur vers une mémoire tampon qui contient la taille maximale en octets des données sous-jacentes de cette colonne
DecimalDigits Sortie Pointeur vers une mémoire tampon qui contient les chiffres décimaux des données sous-jacentes de cette colonne, tel que défini par les chiffres décimaux. Si le nombre de chiffres décimaux ne peut pas être déterminé ou n’est pas applicable, la valeur est ignorée
Nullable Sortie Pointeur vers une mémoire tampon qui contient une valeur, qui indique si cette colonne peut contenir des NULL valeurs. Valeurs possibles :

- SQL_NO_NULLS: la colonne ne peut pas contenir de NULL valeurs.
- SQL_NULLABLE: la colonne peut contenir des NULL valeurs.
Si d’autres valeurs sont passées, l’exécution s’arrête

GetResults

Récupérer le jeu de résultats à partir de l’exécution du @script dans sp_execute_external_script.

Cette fonction peut être appelée plusieurs fois. une fois pour chaque flux de blocs et pour chaque partition du @input_data_1_partition_by_columns dans sp_execute_external_script.

Syntaxe

SQLRETURN GetResults(
    SQLGUID         SessionId,
    SQLUSMALLINT    TaskId,
    SQLULEN*        RowsNumber,
    SQLPOINTER**    Data,
    SQLINTEGER***   StrLen_or_Ind
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête
RowsNumber Sortie Pointeur vers une mémoire tampon qui contient le nombre de lignes dans le Data
Data Sortie Pointeur vers un tableau à deux dimensions alloué par l’extension qui contient le jeu de résultats de @script sp_execute_external_script.

Le nombre total de colonnes doit être OutputSchemaColumnsNumber récupéré dans l’appel d’exécution. Chaque colonne doit contenir des RowsNumber éléments qui doivent être interprétés en fonction du type de colonne de GetResultColumn
StrLen_or_Ind Sortie Pointeur vers un tableau à deux dimensions alloué par l’extension qui contient l’indicateur length/NULL pour chaque valeur dans Data. Valeurs possibles de chaque cellule :

- n, où n > 0. Indication de la longueur des données en octets
- SQL_NULL_DATA, indiquant une NULL valeur.
Le nombre total de colonnes doit être OutputSchemaColumnsNumber reçu dans l’appel d’exécution. Chaque colonne contient des RowsNumber éléments qui doivent être interprétés en fonction du type de colonne de GetResultColumn.
StrLen_or_Ind[col]est ignoré, si une colonne n’est pas nullable et ne représente pas l’un des types de données suivants : SQL_C_CHARet SQL_C_WCHARSQL_C_BINARY[add dates]. Sinon, il pointe vers un tableau valide avec RowsNumber des éléments, chaque élément contient sa longueur ou ses données d’indicateur Null

GetOutputParam

Récupérer les informations relatives à un paramètre de sortie donné pour une session particulière.

Cette fonction est appelée pour chaque paramètre de @params sp_execute_external_script marqué avec OUTPUT.

Syntaxe

SQLRETURN GetOutputParam(
    SQLGUID        SessionId,
    SQLUSMALLINT   ParamNumber,
    SQLPOINTER*    ParamValue,
    SQLINTEGER*    StrLen_or_Ind
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
ParamValue Sortie Pointeur vers une mémoire tampon contenant la valeur du paramètre
StrLen_or_Ind Sortie Pointeur vers une mémoire tampon qui contient une valeur entière indiquant la longueur en octets de ParamValue, ou SQL_NULL_DATA pour indiquer que les données sont NULL

GetInterfaceVersion

Récupérer la version de l’interface.

Cette fonction retourne un entier représentant la version de l’interface de l’extension.

Valeurs prises en charge :

  1. La version 1 est la version initiale de l’API. Prise en charge à SQL Server 2019 (15.x) RTM.
  2. La version 2 a ajouté la prise en charge et InstallExternalLibraryUninstallExternalLibrary l’API et est prise en charge à partir de SQL Server 2019 (15.x) CU 3.

Syntaxe

SQLUSMALLINT GetInterfaceVersion();

CleanupSession

Nettoyer les informations par session.

Syntaxe

SQLRETURN CleanupSession(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête

Nettoyage

Nettoyer les informations globales et partagées (par exemple JVM).

Syntaxe

SQLRETURN Cleanup();

GetTelemetryResults

Récupère les données de télémétrie (paires clé-valeur) à partir de l’extension. La fonction est facultative et ne nécessite pas d’implémentation. La télémétrie est exposée par la vue de gestion dynamique (DMV) dm_db_external_script_execution_stats.

Il existe un compteur nommé script_executions, qui est envoyé par l’infrastructure. L’extension ne doit pas utiliser ce nom.

Chaque entrée de télémétrie est une paire clé-valeur. Les clés sont des chaînes. Les valeurs sont des entiers 64 bits ou des compteurs. Ainsi, la sortie comprend deux tableaux logiques : les noms et les compteurs correspondants. Chaque tableau est une sortie.

La longueur de chaque tableau est RowsNumber, qui est une sortie. La première sortie logique contient des pointeurs vers des chaînes. Elle est représentée par deux tableaux : CounterNames (les données de chaîne réelles) et CounterNamesLength (longueur de chaque chaîne). La deuxième sortie logique est stockée dans le CounterValues pointeur.

Syntaxe

SQLRETURN GetTelemetryResults(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId,
    SQLUINTEGER    *RowsNumber,
    SQLCHAR        ***CounterNames,
    SQLINTEGER     **CounterNamesLength,
    SQLBIGINT      **CounterValues
);

Arguments

Argument Entrée/sortie Description
SessionId Input GUID identifiant de façon unique cette session de script
TaskId Input Entier identifiant de façon unique ce processus d’exécution.

Lorsqu’elle @parallel se trouve 1 dans sp_execute_external_script, cette valeur est comprise entre 0 le degré de parallélisme de la requête
RowsNumber Sortie Nombre de paires clé-valeur
CounterNames Sortie Données de chaîne contenant les clés
CounterNamesLength Sortie Longueur de chaque chaîne de clé
CounterValues Sortie Données entières 64 bits contenant les valeurs

InstallExternalLibrary

Installe une bibliothèque. La fonction est facultative et ne nécessite pas d’implémentation. L’implémentation par défaut consiste à copier le contenu de la bibliothèque (voir CREATE EXTERNAL LIBRARY) dans un fichier situé au bon emplacement. Le nom de fichier est le nom de la bibliothèque.

Syntaxe

SQLRETURN InstallExternalLibrary(
    SQLGUID    SetupSessionId,
    SQLCHAR    *LibraryName,
    SQLINTEGER LibraryNameLength,
    SQLCHAR    *LibraryFile,
    SQLINTEGER LibraryFileLength,
    SQLCHAR    *LibraryInstallDirectory,
    SQLINTEGER LibraryInstallDirectoryLength,
    SQLCHAR    **LibraryError,
    SQLINTEGER *LibraryErrorLength
);

Arguments

Argument Entrée/sortie Description
SetupSessionId Input GUID identifiant de façon unique cette session de script
LibraryName Input Nom de la bibliothèque
LibraryNameLength Input Longueur du nom de la bibliothèque
LibraryFile Input Chemin d’accès (sous forme de chaîne) au fichier de bibliothèque contenant le contenu binaire spécifié par CREATE EXTERNAL LIBRARY
LibraryFileLength Input Longueur de la LibraryFile chaîne
LibraryInstallDirectory Input Répertoire racine pour installer la bibliothèque
LibraryInstallDirectoryLength Input Longueur de la LibraryInstallDirectory chaîne
LibraryError Sortie Paramètre de sortie facultatif. En cas d’erreur lors de l’installation de la bibliothèque, LibraryError pointe vers une chaîne décrivant l’erreur
LibraryErrorLength Sortie Longueur de la LibraryError chaîne

UninstallExternalLibrary

Désinstalle une bibliothèque. La fonction est facultative et ne nécessite pas d’implémentation. L’implémentation par défaut consiste à annuler le travail effectué par l’implémentation par défaut de InstallExternalLibrary. L’implémentation par défaut supprime le contenu du LibraryName fichier sous LibraryInstallDirectory.

Syntaxe

SQLRETURN UninstallExternalLibrary(
    SQLGUID    SetupSessionId,
    SQLCHAR    *LibraryName,
    SQLINTEGER LibraryNameLength,
    SQLCHAR    *LibraryInstallDirectory,
    SQLINTEGER LibraryInstallDirectoryLength,
    SQLCHAR    **LibraryError,
    SQLINTEGER *LibraryErrorLength
);

Arguments

Argument Entrée/sortie Description
SetupSessionId Input GUID identifiant de façon unique cette session de script
LibraryName Input Nom de la bibliothèque
LibraryNameLength Input Longueur du nom de la bibliothèque
LibraryFile Input Chemin d’accès (sous forme de chaîne) au fichier de bibliothèque contenant le contenu binaire spécifié par CREATE EXTERNAL LIBRARY
LibraryFileLength Input Longueur de la LibraryFile chaîne
LibraryInstallDirectory Input Répertoire racine pour installer la bibliothèque
LibraryInstallDirectoryLength Input Longueur de la LibraryInstallDirectory chaîne
LibraryError Sortie Chaîne d’erreur de bibliothèque
LibraryErrorLength Sortie Longueur de la LibraryError chaîne