Python 外掛程式

發行項
01/23/2024

Python 外掛程式會使用 Python 指令碼執行使用者定義函數 (UDF)。 Python 指令碼會取得表格式資料作為其輸出，並產生表格式輸出。外掛程式的執行階段是由沙箱中主控，在叢集節點上執行。

語法

T|evaluate [ (per_nodesingle | ) ] [=hint.remote=hint.distribution () ] output_schemalocal | auto腳本 [script_parameters] python(, [,,external_artifacts][,spill_to_disk])

深入瞭解語法慣例。

參數

名稱	類型	必要	Description
output_schema	`string`	✔️	`type`常值，定義 Python 程式代碼所傳回之表格式數據的輸出架構。格式：`typeof(`ColumnName`:`ColumnType[, ...]`)`，例如：`typeof(col1:string, col2:long)`。若要延伸輸入結構描述，請使用下列語法：`typeof(*, col1:string, col2:long)`。
指令碼	`string`	✔️	要執行的有效 Python 腳本。若要產生多行字串，請參閱使用方式秘訣。
script_parameters	`dynamic`		要傳遞至 Python 腳本做為保留 `kargs` 字典之名稱值組的屬性包。如需詳細資訊，請參閱保留的 Python 變數。
hint.distribution	`string`		外掛程式執行要分散到多個叢集節點的提示。預設值是 `single`。 `single` 表示文稿的單一實例會在整個查詢數據上執行。 `per_node` 表示如果 Python 區塊散發前的查詢，文稿的實例將會在每個節點上執行，而該腳本包含的數據則為。
hint.remote	`string`		此提示僅適用於跨叢集查詢。預設值是 `auto`。 `auto` 表示伺服器會自動決定執行 Python 程式代碼的叢集。將值設定為 `local` 強制在本機叢集上執行 Python 程式代碼。在遠端叢集上停用 Python 外掛程式時，請使用它。
external_artifacts	`dynamic`		可從雲端記憶體存取之成品的屬性包名稱和URL組。如需詳細資訊，請參閱使用外部成品。
spill_to_disk	`bool`		指定將輸入數據表串行化為 Python 沙箱的替代方法。若要序列化大型資料表，請將其設定為 `true` 以加速序列化，並大幅降低沙箱記憶體耗用量。預設為 `true`。

保留的 Python 變數

針對 Kusto 查詢語言和 Python 程式碼之間的互動，已保留下列變數。

df：輸入表格式資料 (T 上方的值)，作為 pandas DataFrame。
kargs：script_parameters 引數的值，作為 Python 字典。
result：Python 指令碼所建立的 pandas 資料框架，其值會變成表格式資料，傳送至外掛程式之後的 Kusto 查詢運算子。

啟用外掛程式

外掛程式預設為停用。開始之前，請先檢閱必要條件清單。若要啟用外掛程式並選取 Python 映像的版本，請參閱在叢集上啟用語言延伸模組。

Python 沙箱映像

若要變更 Python 映射的版本，請參閱變更叢集上的 Python 語言延伸模組映像。

若要查看不同 Python 映像的套件清單，請參閱 Python 套件參考。

注意

根據預設，外掛程式會將 numpy 匯入為 np ，並將 pandas 匯入為 pd。您可以選擇性地視需要匯入其他模組。
某些套件可能與外掛程式執行所在沙箱所強制執行的限制不相容。

使用查詢和更新原則的擷取

在下列查詢中使用外掛程式：
- 定義為更新原則的一部分，其來源資料表會內嵌為使用「非串流」內嵌。
- 作為從查詢內嵌命令的一部分來執行，例如 .set-or-append。
您無法在定義為更新原則一部分的查詢中使用此外掛程式，其來源資料表是使用串流內嵌進行內嵌。

範例

range x from 1 to 360 step 1
| evaluate python(
//
typeof(*, fx:double),               //  Output schema: append a new fx column to original table 
```
result = df
n = df.shape[0]
g = kargs["gain"]
f = kargs["cycles"]
result["fx"] = g * np.sin(df["x"]/n*2*np.pi*f)
```
, bag_pack('gain', 100, 'cycles', 4)    //  dictionary of parameters
)
| render linechart

顯示查詢結果的正弦示範螢幕快照。

print "This is an example for using 'external_artifacts'"
| evaluate python(
    typeof(File:string, Size:string), ```if 1:
    import os
    result = pd.DataFrame(columns=['File','Size'])
    sizes = []
    path = '.\\\\Temp'
    files = os.listdir(path)
    result['File']=files
    for file in files:
        sizes.append(os.path.getsize(path + '\\\\' + file))
    result['Size'] = sizes
    ```,
    external_artifacts = 
        dynamic({"this_is_my_first_file":"https://kustoscriptsamples.blob.core.windows.net/samples/R/sample_script.r",
                 "this_is_a_script":"https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py"})
)

檔案	大小
this_is_a_script	120
this_is_my_first_file	105

效能秘訣

將外掛程式的輸入數據集縮減為 (資料行/資料列所需的最小數量) 。
- 盡可能搭配 Kusto 的查詢語言，在來源數據集上使用篩選。
- 若要在來源資料行的子集上進行計算，請先僅估計這些資料行，再叫用外掛程式。
在指令碼中的邏輯可散佈時使用 hint.distribution = per_node。
- 您也可以使用資料分割運算符來分割輸入數據集。
請盡可能使用 Kusto 的查詢語言來實作 Python 指令碼的邏輯。

使用提示

若要在查詢編輯器中產生包含 Python 腳本的多行字串，請從您慣用的 Python 編輯器中複製 Python 腳本， (Jupyter、Visual Studio Code、PyCharm 等等) ，將它貼到查詢編輯器中，然後在包含三個連續反引號的行之間括住完整的腳本。例如：

```
python code
```
使用 externaldata 運算子來取得您儲存在外部位置的指令碼內容，例如 Azure Blob 儲存體。

範例

    let script = 
        externaldata(script:string)
        [h'https://kustoscriptsamples.blob.core.windows.net/samples/python/sample_script.py']
        with(format = raw);
    range x from 1 to 360 step 1
    | evaluate python(
        typeof(*, fx:double),
        toscalar(script), 
        bag_pack('gain', 100, 'cycles', 4))
    | render linechart

使用外部成品

您可以從雲端記憶體取得外部成品供腳本使用，並在運行時間使用。

外部成品屬性所參考的 URL 必須是：

包含在叢集的註標原則中。
在公開可用的位置，或提供必要的認證，如儲存體連接字串中所述。

注意

使用受控識別驗證外部成品時， SandboxArtifacts 必須在叢集層級受控識別原則上定義使用方式。

成品可供指令碼從本機臨時目錄 (.\Temp) 使用。屬性包中提供的名稱是用來做為本機檔案名稱。請參閱範例。

如需參考外部套件的相關信息，請參閱安裝 Python 外掛程式的套件。

重新整理外部成品快取

查詢中使用的外部成品檔案會在叢集上快取。如果您對雲端記憶體中的檔案進行更新，且需要立即與您的叢集同步處理，您可以使用 .clear 叢集快取外部成品命令。此命令會清除快取的檔案，並確保後續的查詢會以最新版本的成品執行。