SQL Server 用の機能拡張フレームワーク API

適用対象: SQL Server 2019 (15.x) 以降のバージョン

機能拡張フレームワークを使用すると、SQL Server のプログラミング言語拡張機能を記述できます。 SQL Server 用 Extensibility Framework API は、SQL Server との対話やデータの交換に言語拡張機能で使用できる API です。

言語拡張機能の作成者は、このリファレンスをオープンソースの言語拡張機能と共に使用して、独自のものを記述するための API の使用方法を理解することができます。言語拡張機能のソースコードは、aka.ms/mssql-lang-extensions で見つけることができます。

この記事では、すべての API 関数に関する構文と引数の情報を確認できます。

戻り値

すべての関数は、 SQLRETURN パラメーターを返します。値が SQL_SUCCESS以外の場合、値はエラーとして扱われ、スクリプトの実行が停止します。

標準出力

標準出力ストリームまたはエラーストリームに対する拡張機能による出力はすべて、セッションのログファイルにトレースされ、最終的に SQL Server にトレースされます。これは、SQL Server Management Studio (SSMS) の [メッセージ] タブに表示される内容と似ています。

Init

この関数は 1 回だけ呼び出され、実行用にランタイムを初期化するために使用されます。

構文

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

引数

Argument	入力/出力	説明
`ExtensionParams`	入力	CREATE EXTERNAL LANGUAGE または ALTER EXTERNAL LANGUAGE 中に指定された`PARAMETERS`値を含む null で終わる文字列
`ExtensionParamsLength`	入力	`ExtensionParams`のバイト単位の長さ (null 終端文字を除く)
`ExtensionPath`	入力	拡張機能のインストールディレクトリへの絶対パスを含む NULL で終わる UTF-8 文字列
`ExtensionPathLength`	入力	`ExtensionPath`のバイト単位の長さ (null 終端文字を除く)
`PublicLibraryPath`	入力	この外部言語のパブリック外部ライブラリディレクトリへの絶対パスを含む NULL で終わる UTF-8 文字列
`PublicLibraryPathLength`	入力	`PublicLibraryPath`のバイト単位の長さ (null 終端文字を除く)
`PrivateLibraryPath`	入力	このユーザーとこの外部言語のプライベート外部ライブラリディレクトリへの絶対パスを含む NULL 終端 UTF-8 文字列
`PrivateLibraryPathLength`	入力	`PrivateLibraryPath`のバイト単位の長さ (null 終端文字を除く)

InitSession

この関数は、セッションごとに 1 回呼び出され、セッション固有の設定を初期化します。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。
`Script`	入力	sp_execute_external_scriptの`@script`を含む null で終わる UTF-8 文字列
`ScriptLength`	入力	`ScriptScript`のバイト単位の長さ (null 終端文字を除く)
`InputSchemaColumnsNumber`	入力	sp_execute_external_scriptの`@input_data_1`からの結果セット内の列数
`ParametersNumber`	入力	sp_execute_external_scriptの`@params`からの入力パラメーターの数
`InputDataName`	入力	sp_execute_external_scriptの`@input_data_1_name`を含む null で終わる UTF-8 文字列
`InputDataNameLength`	入力	`InputDataName`のバイト単位の長さ (null 終端文字を除く)
`OutputDataName`	入力	sp_execute_external_scriptの`@output_data_1_name`を含む null で終わる UTF-8 文字列
`OutputDataNameLength`	入力	`OutputDataName`のバイト単位の長さ (null 終端文字を除く)

InitColumn

特定のセッションの指定された列の情報を初期化します。

この関数は、sp_execute_external_script 内の @input_data_1 の結果セットの各列に対して呼び出されます。

この結果セットの列構造は、 input スキーマと呼ばれます。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。
`ColumnNumber`	入力	入力スキーマ内のこの列のインデックスを識別する整数。列の番号は、次の位置から順に番号付けされます。 `0`
`ColumnName`	入力	列の名前を含む NULL で終わる UTF-8 文字列
`ColumnNameLength`	入力	`ColumnName`のバイト単位の長さ (null 終端文字を除く)
`Data type`	入力	この列のデータ型を識別する ODBC C 型
`ColumnSize`	入力	この列の基になるデータの最大サイズ (バイト単位)。 `SQL_C_CHAR`、`SQL_C_WCHAR`、および`SQL_C_BINARY`のデータ型の場合、8,000 を超える値は、この列が LOB オブジェクトを表し、サイズは最大 2 GB であることを示します
`DecimalDigits`	入力	Decimal Digits で定義されている、この列の基になるデータの 10 進数
`Nullable`	入力	この列に `NULL` 値が含まれるかどうかを示す値。指定できる値 - `SQL_NO_NULLS`: 列に `NULL` 値を含めることはできません。 - `SQL_NULLABLE`: 列には `NULL` 値を含めることができます
`PartitionByNumber`	入力	sp_execute_external_scriptの`@input_data_1_partition_by_columns` シーケンス内のこの列のインデックスを示す値。列には、 `0`から順番に番号が付けられます。この列がシーケンスに含まれていない場合、値は -1 です
`OrderByNumber`	入力	sp_execute_external_scriptの`@input_data_1_order_by_columns` シーケンス内のこの列のインデックスを示す値。列には、 `0`から順番に番号が付けられます。この列がシーケンスに含まれていない場合、値は -1 です

InitParam

特定のセッションの指定された入力パラメーターに関する情報を初期化します。

この関数は、sp_execute_external_script 内の @params の各パラメーターに対して呼び出されます。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。
`ParamNumber`	入力	このパラメーターのインデックスを識別する整数。パラメーターの番号は、次の位置から順番に番号付けされます。 `0`
`ParamName`	入力	パラメーターの名前を含む NULL で終わる UTF-8 文字列
`ParamNameLength`	入力	`ParamName`のバイト単位の長さ (null 終端文字を除く)
`Data type`	入力	このパラメーターのデータ型を識別する ODBC C 型
`ParamSize`	入力	このパラメーターの基になるデータの最大サイズ (バイト単位)。 `SQL_C_CHAR`、`SQL_C_WCHAR`、および`SQL_C_BINARY`のデータ型の場合、8000 を超える値は、このパラメーターが LOB オブジェクトを表し、最大サイズが 2 GB であることを示します
`DecimalDigits`	入力	このパラメーターの基になるデータの 10 進数 ( Decimal Digits で定義)。
`ParamValue`	入力	パラメーターの値を含むバッファーへのポインター
`StrLen_or_Ind`	入力	`ParamValue`の長さをバイト単位で示す整数値。データが`NULL`されていることを示す`SQL_NULL_DATA`。 `StrLen_or_Ind[col]` 列が null 許容ではなく、 `SQL_C_CHAR`、 `SQL_C_WCHAR` 、 `SQL_C_BINARY`、 `SQL_C_NUMERIC` 、または `SQL_C_TYPE_TIMESTAMP`のいずれかのデータ型を表していない場合は無視できます。それ以外の場合は、 `RowsNumber` 要素を持つ有効な配列を指します。各要素には、その長さまたは null インジケーターデータが含まれています
`InputOutputType`	入力	パラメーターの型。 `InputOutputType`引数は、次のいずれかの値です。 - `SQL_PARAM_INPUT` - `SQL_PARAM_INPUT_OUTPUT`

実行

sp_execute_external_script 内の @script を実行します。

この関数は複数回呼び出される場合があります。各ストリームチャンクにつき 1 回と、sp_execute_external_script 内の @input_data_1_partition_by_columns の各パーティションに対して 1 回です。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。
`RowsNumber`	入力	内の行数 `Data`
`Data`	入力	sp_execute_external_script内の`@input_data_1`の結果セットを含む 2 次元配列。 InitSession呼び出しで受信した列の合計数が`InputSchemaColumnsNumber`されます。各列には、`RowsNumber`InitColumn の列の型に従って解釈する必要がある要素含まれています。 `StrLen_or_Ind`で`NULL`される要素は有効であるとは限らないので、無視する必要があります
`StrLen_or_Ind`	入力	`Data`の各値の長さ/NULL インジケーターを含む 2 次元配列。各セルの使用可能な値: - `n`を `n > 0`します。データの長さ (バイト単位) を示します。 - `SQL_NULL_DATA`: `NULL` 値を示します。 InitSession呼び出しで受信した列の合計数が`InputSchemaColumnsNumber`されます。各列には、`RowsNumber`InitColumn の列の型に従って解釈する必要がある要素含まれています。 `StrLen_or_Ind[col]` は、1 つの列が null 許容ではなく、 `SQL_C_CHAR`、 `SQL_C_WCHAR` 、 `SQL_C_BINARY`、 `SQL_C_NUMERIC` 、または `SQL_C_TYPE_TIMESTAMP`のいずれかのデータ型を表していない場合は無視できます。それ以外の場合は、 `RowsNumber` 要素を持つ有効な配列を指します。各要素には、その長さまたは null インジケーターデータが含まれます
`OutputSchemaColumnsNumber`	出力	sp_execute_external_scriptの`@script`の予想される結果セット内の列数を返すバッファーへのポインター

GetResultColumn

特定のセッションの指定された出力列に関する情報を取得します。

この関数は、sp_execute_external_script 内の @script の結果セットの各列に対して呼び出されます。

この結果セットの列構造は、 出力スキーマと呼ばれます。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。
`ColumnNumber`	入力	出力スキーマ内のこの列のインデックスを識別する整数。列の番号は、次の位置から順に番号付けされます。 `0`
`Data type`	出力	この列のデータ型を識別する ODBC C 型を含むバッファーへのポインター
`ColumnSize`	出力	この列の基になるデータの最大サイズ (バイト単位) を含むバッファーへのポインター
`DecimalDigits`	出力	Decimal Digits で定義されている、この列の基になるデータの 10 進数を含むバッファーへのポインター。 10 進数の桁数を特定できない場合、または該当しない場合、値は破棄されます。
`Nullable`	出力	値を含むバッファーへのポインター。この列に `NULL` 値が含まれている可能性があるかどうかを示します。指定できる値 - `SQL_NO_NULLS`: 列に `NULL` 値を含めることはできません。 - `SQL_NULLABLE`: 列には `NULL` 値を含めることができます。他の値が渡された場合、実行は停止します

GetResults

sp_execute_external_script 内の @script を実行した結果セットを取得します。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。
`RowsNumber`	出力	内の行数を含むバッファーへのポインター `Data`
`Data`	出力	sp_execute_external_scriptの`@script`の結果セットを含む拡張機能によって割り当てられた 2 次元配列へのポインター。 Execute呼び出しで取得された列の合計数を`OutputSchemaColumnsNumber`する必要があります。各列には `RowsNumber` 要素が含まれている必要があります。この要素は、 GetResultColumn の列の種類に従って解釈する必要があります。
`StrLen_or_Ind`	出力	`Data`内の各値の長さ/NULL インジケーターを含む拡張機能によって割り当てられた 2 次元配列へのポインター。各セルの使用可能な値: - `n`を `n > 0`します。データの長さ (バイト単位) を示します。 - `SQL_NULL_DATA`: `NULL` 値を示します。 Execute 呼び出しで受信した列の合計数を`OutputSchemaColumnsNumber`する必要があります。各列には、GetResultColumn の列の種類に従って解釈する必要がある`RowsNumber`要素が含まれています。 `StrLen_or_Ind[col]` は、1 つの列が null 許容ではなく、 `SQL_C_CHAR`、 `SQL_C_WCHAR` 、 `SQL_C_BINARY` `[add dates]`のいずれかのデータ型を表していない場合は無視されます。それ以外の場合は、 `RowsNumber` 要素を持つ有効な配列を指します。各要素には、その長さまたは null インジケーターデータが含まれます

GetOutputParam

特定のセッションの指定された出力パラメーターに関する情報を取得します。

この関数は、OUTPUTでマークされたsp_execute_external_scriptの@paramsから各パラメーターに対して呼び出されます。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`ParamValue`	出力	パラメーターの値を含むバッファーへのポインター
`StrLen_or_Ind`	出力	`ParamValue`のバイト単位の長さを示す整数値を含むバッファーへのポインター、またはデータが次の値であることを示す`SQL_NULL_DATANULL`

GetInterfaceVersion

インターフェイスのバージョンを取得します。

この関数からは、拡張機能のインターフェイスのバージョンを表す整数が返されます。

サポートされる値:

バージョン 1 は初期 API バージョンです。 SQL Server 2019 (15.x) RTM でサポートされます。
バージョン 2 では、 InstallExternalLibrary および UninstallExternalLibrary API のサポートが追加され、SQL Server 2019 (15.x) CU 3 からサポートされています。

構文

SQLUSMALLINT GetInterfaceVersion();

CleanupSession

セッションごとの情報をクリーンアップします。

構文

SQLRETURN CleanupSession(
    SQLGUID        SessionId,
    SQLUSMALLINT   TaskId
);

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。

クリーンアップ

グローバルな共有情報 (JVM など) をクリーンアップします。

構文

SQLRETURN Cleanup();

GetTelemetryResults

拡張機能からテレメトリ (キーと値のペア) データを取得します。この関数はオプションであり、実装する必要はありません。テレメトリは dm_db_external_script_execution_stats 動的管理ビュー (DMV) によって公開されます。

フレームワークによって送信される script_executions という名前のカウンターがあります。拡張機能では、この名前を使用しないでください。

各テレメトリエントリはキーと値のペアです。キーは文字列です。値は 64 ビット整数またはカウンターです。したがって、出力は 2 つの論理配列 (名前とそれに対応するカウンター) で構成されます。各配列は出力です。

各配列の長さは RowsNumberです。これは出力です。最初の論理出力には、文字列へのポインターが含まれています。これは、 CounterNames (実際の文字列データ) と CounterNamesLength (各文字列の長さ) の 2 つの配列で表されます。 2 番目の論理出力は、 CounterValues ポインターに格納されます。

構文

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

引数

Argument	入力/出力	説明
`SessionId`	入力	このスクリプトセッションを一意に識別する GUID
`TaskId`	入力	この実行プロセスを一意に識別する整数。 `@parallel`がsp_execute_external_scriptで`1`されている場合、この値の範囲は`0`からクエリの並列処理の次数までです。
`RowsNumber`	出力	キーと値のペアの数
`CounterNames`	出力	キーを含む文字列データ
`CounterNamesLength`	出力	各キー文字列の長さ
`CounterValues`	出力	値を含む 64 ビット整数データ

InstallExternalLibrary

ライブラリをインストールします。この関数はオプションであり、実装する必要はありません。既定の実装では、ライブラリの内容を適切な場所のファイルにコピーします (CREATE EXTERNAL LIBRARY を参照)。ファイル名はライブラリ名です。

構文

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

引数

Argument	入力/出力	説明
`SetupSessionId`	入力	このスクリプトセッションを一意に識別する GUID
`LibraryName`	入力	ライブラリ名
`LibraryNameLength`	入力	ライブラリ名の長さ
`LibraryFile`	入力	CREATE EXTERNAL LIBRARY で指定されたバイナリコンテンツを含むライブラリファイルへのパス (文字列として)
`LibraryFileLength`	入力	`LibraryFile`文字列の長さ
`LibraryInstallDirectory`	入力	ライブラリをインストールするルートディレクトリ
`LibraryInstallDirectoryLength`	入力	`LibraryInstallDirectory`文字列の長さ
`LibraryError`	出力	省略可能な出力パラメーター。ライブラリのインストール中にエラーが発生した場合、 `LibraryError` はエラーを説明する文字列を指します
`LibraryErrorLength`	出力	`LibraryError`文字列の長さ

UninstallExternalLibrary

ライブラリをアンインストールします。この関数はオプションであり、実装する必要はありません。既定の実装では、 InstallExternalLibraryの既定の実装によって行われた作業を元に戻します。既定の実装では、LibraryInstallDirectoryの下にあるLibraryName ファイルの内容が削除されます。

構文

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

引数

Argument	入力/出力	説明
`SetupSessionId`	入力	このスクリプトセッションを一意に識別する GUID
`LibraryName`	入力	ライブラリ名
`LibraryNameLength`	入力	ライブラリ名の長さ
`LibraryFile`	入力	で指定されたバイナリコンテンツを含むライブラリファイルへのパス (文字列として) `CREATE EXTERNAL LIBRARY`
`LibraryFileLength`	入力	`LibraryFile`文字列の長さ
`LibraryInstallDirectory`	入力	ライブラリをインストールするルートディレクトリ
`LibraryInstallDirectoryLength`	入力	`LibraryInstallDirectory`文字列の長さ
`LibraryError`	出力	ライブラリエラー文字列
`LibraryErrorLength`	出力	`LibraryError`文字列の長さ

フィードバック

このページはお役に立ちましたか?

Last updated on 2025-12-10