API del framework di estendibilità per SQL Server

Si applica a: SQL Server 2019 (15.x) e versioni successive

È possibile usare il framework di estendibilità per scrivere estensioni dei linguaggi di programmazione per SQL Server. L'API Extensibility Framework per SQL Server è un'API che può essere usata da un'estensione del linguaggio per interagire con e scambiare dati con SQL Server.

Gli autori di estensioni di linguaggio possono usare questo documento di riferimento con le estensioni di linguaggio open source per capire come usare l'API per scrivere estensioni personalizzate. Il codice sorgente per le estensioni di linguaggio è disponibile all'indirizzo aka.ms/mssql-lang-extensions.

È possibile trovare le informazioni sulla sintassi e sugli argomenti su tutte le funzioni API in questo articolo.

Valore restituito

Tutte le funzioni restituiscono un SQLRETURN parametro. Se il valore è diverso da SQL_SUCCESS, il valore viene considerato come un errore e l'esecuzione dello script viene arrestata.

Output standard

Qualsiasi output dell'estensione per l'output standard o i flussi di errore vengono tracciati nel file di log della sessione e vengono infine ricontracciati in SQL Server. Questo è simile a qualsiasi elemento visualizzato nella scheda Messaggi di SQL Server Management Studio (SSMS).

Init

Questa funzione viene chiamata una sola volta ed è usata per inizializzare il runtime per l'esecuzione.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
ExtensionParams Input Stringa terminata a nullo contenente PARAMETERS valore fornito durante CREATE EXTERNAL LANGUAGE o ALTER EXTERNAL LANGUAGE
ExtensionParamsLength Input Lunghezza in byte di (escluso il carattere di ExtensionParams terminazione Null)
ExtensionPath Input Stringa UTF-8 con terminazione Null contenente il percorso assoluto della directory di installazione dell'estensione
ExtensionPathLength Input Lunghezza in byte di (escluso il carattere di ExtensionPath terminazione Null)
PublicLibraryPath Input Stringa UTF-8 con terminazione Null contenente il percorso assoluto della directory delle librerie esterne pubbliche per questo linguaggio esterno
PublicLibraryPathLength Input Lunghezza in byte di (escluso il carattere di PublicLibraryPath terminazione Null)
PrivateLibraryPath Input Stringa UTF-8 con terminazione Null contenente il percorso assoluto della directory delle librerie esterne private per questo utente e questo linguaggio esterno
PrivateLibraryPathLength Input Lunghezza in byte di (escluso il carattere di PrivateLibraryPath terminazione Null)

InitSession

Questa funzione viene chiamata una volta per sessione e inizializza le impostazioni specifiche della sessione.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query
Script Input Stringa UTF-8 con terminazione Null contenente in @scriptsp_execute_external_script
ScriptLength Input Lunghezza in byte di (escluso il carattere di ScriptScript terminazione Null)
InputSchemaColumnsNumber Input Numero di colonne nel set di risultati da @input_data_1 in sp_execute_external_script
ParametersNumber Input Numero di parametri di input da @params in sp_execute_external_script
InputDataName Input Stringa UTF-8 con terminazione Null contenente in @input_data_1_namesp_execute_external_script
InputDataNameLength Input Lunghezza in byte di (escluso il carattere di InputDataName terminazione Null)
OutputDataName Input Stringa UTF-8 con terminazione Null contenente in @output_data_1_namesp_execute_external_script
OutputDataNameLength Input Lunghezza in byte di (escluso il carattere di OutputDataName terminazione Null)

InitColumn

Consente di inizializzare le informazioni relative a una determinata colonna in una sessione specifica.

Questa funzione viene chiamata per ogni colonna del set di risultati di @input_data_1 in sp_execute_external_script.

La struttura di colonna di questo set di risultati viene definita schema di input.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query
ColumnNumber Input Intero che identifica l'indice di questa colonna nello schema di input. Le colonne vengono numerate in sequenza in ordine crescente a partire da 0
ColumnName Input Stringa UTF-8 con terminazione Null contenente il nome della colonna
ColumnNameLength Input Lunghezza in byte di (escluso il carattere di ColumnName terminazione Null)
Data type Input Tipo ODBC C che identifica il tipo di dati di questa colonna
ColumnSize Input Dimensione massima in byte dei dati sottostanti in questa colonna.

Per SQL_C_CHARi tipi di dati e SQL_C_WCHARSQL_C_BINARY i valori maggiori di 8.000 indicano che questa colonna rappresenta un oggetto LOB, con dimensioni fino a 2 GB
DecimalDigits Input Cifre decimali dei dati sottostanti in questa colonna, come definito dalle cifre decimali
Nullable Input Valore che indica se questa colonna potrebbe contenere NULL valori. Valori possibili:

- SQL_NO_NULLS: la colonna non può contenere NULL valori.
- SQL_NULLABLE: la colonna può contenere NULL valori
PartitionByNumber Input Valore che indica l'indice di questa colonna nella @input_data_1_partition_by_columns sequenza in sp_execute_external_script. Le colonne vengono numerate in sequenza in ordine crescente a partire da 0. Se questa colonna non è inclusa nella sequenza, il valore è -1
OrderByNumber Input Valore che indica l'indice di questa colonna nella @input_data_1_order_by_columns sequenza in sp_execute_external_script. Le colonne vengono numerate in sequenza in ordine crescente a partire da 0. Se questa colonna non è inclusa nella sequenza, il valore è -1

InitParam

Consente di inizializzare le informazioni relative a un determinato parametro di input in una sessione specifica.

Questa funzione viene chiamata per ogni parametro di @params in sp_execute_external_script.

Sintassi

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
);

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query
ParamNumber Input Intero che identifica l'indice di questo parametro. I parametri vengono numerati in sequenza in ordine crescente a partire da 0
ParamName Input Stringa UTF-8 con terminazione Null contenente il nome del parametro
ParamNameLength Input Lunghezza in byte di (escluso il carattere di ParamName terminazione Null)
Data type Input Tipo ODBC C che identifica il tipo di dati di questo parametro
ParamSize Input Dimensione massima in byte dei dati sottostanti in questo parametro.

Per SQL_C_CHARi tipi di dati e SQL_C_WCHARSQL_C_BINARY , i valori maggiori di 8000 indicano che questo parametro rappresenta l'oggetto LOB e con dimensioni fino a 2 GB
DecimalDigits Input Cifre decimali dei dati sottostanti in questo parametro, come definito da Cifre decimali
ParamValue Input Puntatore a un buffer contenente il valore del parametro
StrLen_or_Ind Input Valore intero che indica la lunghezza in byte di ParamValueo SQL_NULL_DATA per indicare che i dati sono NULL.

StrLen_or_Ind[col]può essere ignorato se una colonna non è nullable e non rappresenta uno dei tipi di dati seguenti: SQL_C_CHAR, SQL_C_WCHAR e SQL_C_BINARYSQL_C_NUMERIC o SQL_C_TYPE_TIMESTAMP. In caso contrario, punta a una matrice valida con RowsNumber elementi, in cui ogni elemento contiene i dati dell'indicatore null o di lunghezza
InputOutputType Input Il tipo di parametro. L'argomento InputOutputType è uno dei valori seguenti:

- SQL_PARAM_INPUT
- SQL_PARAM_INPUT_OUTPUT

Execute

Consente di eseguire @script in sp_execute_external_script.

Questa funzione può essere chiamata più volte. una per ogni blocco di flusso e per ogni partizione nell'oggetto @input_data_1_partition_by_columns in sp_execute_external_script.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query
RowsNumber Input Numero di righe nell'oggetto Data
Data Input Matrice bidimensionale che contiene il set di risultati di @input_data_1 in sp_execute_external_script.

Il numero totale di colonne InputSchemaColumnsNumber è stato ricevuto nella chiamata InitSession . Ogni colonna contiene RowsNumber elementi che devono essere interpretati in base al tipo di colonna di InitColumn.
Gli elementi indicati in NULLStrLen_or_Ind non sono garantiti per essere validi e devono essere ignorati
StrLen_or_Ind Input Matrice bidimensionale che contiene l'indicatore length/NULL per ogni valore in Data. Possibili valori di ogni cella:

- n, dove n > 0. Indica la lunghezza dei dati in byte.
- SQL_NULL_DATA, che indica un NULL valore.
Il numero totale di colonne InputSchemaColumnsNumber è stato ricevuto nella chiamata InitSession . Ogni colonna contiene RowsNumber elementi che devono essere interpretati in base al tipo di colonna di InitColumn.
StrLen_or_Ind[col]può essere ignorato, se una colonna non è nullable e non rappresenta uno dei tipi di dati seguenti: SQL_C_CHAR, SQL_C_WCHAR e SQL_C_BINARYSQL_C_NUMERIC o SQL_C_TYPE_TIMESTAMP. In caso contrario, punta a una matrice valida con RowsNumber elementi, ogni elemento contiene i dati dell'indicatore null o di lunghezza
OutputSchemaColumnsNumber Output Puntatore a un buffer in cui restituire il numero di colonne nel set di risultati previsto di @script in sp_execute_external_script

GetResultColumn

Consente di recuperare le informazioni relative a una determinata colonna di output in una sessione specifica.

Questa funzione viene chiamata per ogni colonna del set di risultati di @script in sp_execute_external_script.

La struttura di colonna di questo set di risultati viene definita schema di output.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query
ColumnNumber Input Intero che identifica l'indice di questa colonna nello schema di output. Le colonne vengono numerate in sequenza in ordine crescente a partire da 0
Data type Output Puntatore al buffer contenente il tipo ODBC C che identifica il tipo di dati di questa colonna
ColumnSize Output Puntatore a un buffer contenente le dimensioni massime in byte dei dati sottostanti in questa colonna
DecimalDigits Output Puntatore a un buffer contenente le cifre decimali dei dati sottostanti in questa colonna, come definito da Cifre decimali. Se il numero di cifre decimali non può essere determinato o non è applicabile, il valore viene rimosso
Nullable Output Puntatore a un buffer contenente un valore, che indica se questa colonna potrebbe contenere NULL valori. Valori possibili:

- SQL_NO_NULLS: la colonna non può contenere NULL valori.
- SQL_NULLABLE: la colonna può contenere NULL valori.
Se vengono passati altri valori, l'esecuzione viene arrestata

GetResults

Consente di recuperare il set di risultati dell'esecuzione di @script in sp_execute_external_script.

Questa funzione può essere chiamata più volte. una per ogni blocco di flusso e per ogni partizione nell'oggetto @input_data_1_partition_by_columns in sp_execute_external_script.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query
RowsNumber Output Puntatore a un buffer contenente il numero di righe nell'oggetto Data
Data Output Puntatore a una matrice bidimensionale allocata dall'estensione che contiene il set di risultati di @script in sp_execute_external_script.

Il numero totale di colonne deve essere OutputSchemaColumnsNumber recuperato nella chiamata Execute . Ogni colonna deve contenere RowsNumber elementi che devono essere interpretati in base al tipo di colonna da GetResultColumn
StrLen_or_Ind Output Puntatore a una matrice bidimensionale allocata dall'estensione che contiene l'indicatore length/NULL per ogni valore in Data. Possibili valori di ogni cella:

- n, dove n > 0. Indica la lunghezza dei dati in byte.
- SQL_NULL_DATA, che indica un NULL valore.
Il numero totale di colonne deve essere OutputSchemaColumnsNumber ricevuto nella chiamata Execute . Ogni colonna contiene RowsNumber elementi che devono essere interpretati in base al tipo di colonna di GetResultColumn.
StrLen_or_Ind[col] viene ignorato, se una colonna non è nullable e non rappresenta uno dei tipi di dati seguenti: SQL_C_CHAR, SQL_C_WCHAR e SQL_C_BINARY[add dates]. In caso contrario, punta a una matrice valida con RowsNumber elementi, ogni elemento contiene i dati dell'indicatore null o di lunghezza

GetOutputParam

Consente di recuperare le informazioni relative a un determinato parametro di output in una sessione specifica.

Questa funzione viene chiamata per ogni parametro da @params in sp_execute_external_script contrassegnata con OUTPUT.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
ParamValue Output Puntatore a un buffer contenente il valore del parametro
StrLen_or_Ind Output Puntatore a un buffer contenente un valore intero che indica la lunghezza in byte di ParamValueo SQL_NULL_DATA per indicare che i dati sono NULL

GetInterfaceVersion

Consente di recuperare la versione dell'interfaccia.

Questa funzione restituisce un numero intero che rappresenta la versione dell'interfaccia dell'estensione.

Valori supportati:

  1. La versione 1 corrisponde alla versione iniziale dell'API, Supportato in SQL Server 2019 (15.x) RTM.
  2. La versione 2 ha aggiunto il supporto per InstallExternalLibrary e UninstallExternalLibrary l'API ed è supportata da SQL Server 2019 (15.x) CU 3.

Sintassi

SQLUSMALLINT GetInterfaceVersion();

CleanupSession

Consente di pulire le informazioni relative a ogni sessione.

Sintassi

SQLRETURN CleanupSession(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId
);

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query

Pulizia

Consente di pulire informazioni condivise a livello globale (ad esempio, JVM).

Sintassi

SQLRETURN Cleanup();

GetTelemetryResults

Consente di recuperare dati di telemetria (coppie chiave-valore) dall'estensione. Questa funzione è facoltativa e non deve essere necessariamente implementata. I dati di telemetria vengono esposti dalla vista a gestione dinamica (DMV) dm_db_external_script_execution_stats.

È presente un contatore denominato script_executions, che viene inviato dal framework. L'estensione non deve usare questo nome.

Ogni voce di telemetria è una coppia chiave-valore, Le chiavi sono stringhe. I valori sono numeri interi a 64 bit o contatori. L'output è costituito quindi da due matrici logiche: i nomi e i contatori corrispondenti. Ogni matrice è un output.

La lunghezza di ogni matrice è RowsNumber, che è un output. Il primo output logico contiene puntatori alle stringhe. È rappresentato da due matrici: CounterNames (i dati stringa effettivi) e CounterNamesLength (la lunghezza di ogni stringa). Il secondo output logico viene archiviato nel CounterValues puntatore.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SessionId Input GUID che identifica in modo univoco questa sessione di script
TaskId Input Intero che identifica in modo univoco questo processo di esecuzione.

Quando @parallel si trova 1 in sp_execute_external_script, questo valore varia dal 0 grado di parallelismo della query
RowsNumber Output Numero di coppie chiave-valore
CounterNames Output Dati stringa contenenti le chiavi
CounterNamesLength Output Lunghezza di ogni stringa di chiave
CounterValues Output Dati integer a 64 bit contenenti i valori

InstallExternalLibrary

Consente di installare una libreria. Questa funzione è facoltativa e non deve essere necessariamente implementata. L'implementazione predefinita consiste nel copiare il contenuto della libreria (vedi CREATE EXTERNAL LIBRARY) in un file nella posizione corretta. Il nome del file è il nome della libreria.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SetupSessionId Input GUID che identifica in modo univoco questa sessione di script
LibraryName Input Nome della libreria
LibraryNameLength Input Lunghezza del nome della libreria
LibraryFile Input Percorso (come stringa) nel file di libreria contenente il contenuto binario specificato da CREATE EXTERNAL LIBRARY
LibraryFileLength Input Lunghezza della LibraryFile stringa
LibraryInstallDirectory Input Directory radice per installare la libreria
LibraryInstallDirectoryLength Input Lunghezza della LibraryInstallDirectory stringa
LibraryError Output Parametro di output facoltativo. Se si verifica un errore durante l'installazione della libreria, LibraryError punta a una stringa che descrive l'errore
LibraryErrorLength Output Lunghezza della LibraryError stringa

UninstallExternalLibrary

Disinstalla una libreria. Questa funzione è facoltativa e non deve essere necessariamente implementata. L'implementazione predefinita consiste nell'annullare il lavoro eseguito dall'implementazione predefinita di InstallExternalLibrary. L'implementazione predefinita elimina il contenuto del LibraryName file in LibraryInstallDirectory.

Sintassi

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

Argomenti

Argomento Input/output Descrizione
SetupSessionId Input GUID che identifica in modo univoco questa sessione di script
LibraryName Input Nome della libreria
LibraryNameLength Input Lunghezza del nome della libreria
LibraryFile Input Percorso (come stringa) nel file di libreria contenente il contenuto binario specificato da CREATE EXTERNAL LIBRARY
LibraryFileLength Input Lunghezza della LibraryFile stringa
LibraryInstallDirectory Input Directory radice per installare la libreria
LibraryInstallDirectoryLength Input Lunghezza della LibraryInstallDirectory stringa
LibraryError Output Stringa di errore della libreria
LibraryErrorLength Output Lunghezza della LibraryError stringa