Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
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:
- La versione 1 corrisponde alla versione iniziale dell'API, Supportato in SQL Server 2019 (15.x) RTM.
- La versione 2 ha aggiunto il supporto per
InstallExternalLibraryeUninstallExternalLibraryl'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 |