共用方式為

Python 外掛程式

  • 發行項

適用於： ✅Microsoft網狀架構✅Azure 數據總管

Python 外掛程式會使用 Python 腳本執行使用者定義函式 (UDF)。 Python 文稿會取得表格式資料做為其輸入，併產生表格式輸出。 外掛程式的運行時間裝載在沙盒中，在叢集的節點上執行。

語法

T | evaluate [ （）] [hint.remote = （auto | per_nodelocal | single）] output_schema,腳本 [ =hint.distribution script_parameters] python([, external_artifacts][, , spill_to_disk])

深入瞭解 語法慣例。

參數

姓名 類型​​ 必要 描述
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 字典。
  • resultpandas:P ython 腳本所建立的數據框架，其值會成為傳送至外掛程式後面 Kusto 查詢運算子的表格式數據。

啟用外掛程式

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

Python 沙盒映射

若要將 Python 映射的版本變更為不同的受控映像或自定義映像，請參閱 變更叢集上的 Python 語言延伸模組映像。

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

注意

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

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

範例

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 叢集快取外部成品命令。 此命令會清除快取的檔案，並確保後續查詢會以最新版本的成品執行。

安裝 Python 外掛程式的套件

在大部分的使用案例中，您可能偏好 建立自定義映像。

您可能想要自行安裝套件，原因如下：

  • 您沒有建立自訂映像的許可權。
  • 套件是私用的。
  • 您偏好建立臨機操作套件安裝以進行測試，而且不希望建立自定義映像的額外負荷。

安裝套件，如下所示：

必要條件

  1. 建立 Blob 容器來裝載套件，最好與您的叢集位於相同位置。 例如， https://artifactswestus.blob.core.windows.net/python假設您的叢集位於美國西部。

  2. 改變叢集的 註標原則 ，以允許存取該位置。

    • 這項變更需要 AllDatabasesAdmin 許可權。

    • 例如，若要啟用中 https://artifactswestus.blob.core.windows.net/pythonBlob 的存取權，請執行下列命令：

    .alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'

安裝套件

  1. 對於 PyPi 或其他通道中的公用套件，請下載套件及其相依性。

    • 從本機 Windows Python 環境中的 Cmd 視窗中，執行：
    pip wheel [-w download-dir] package-name.

  2. 建立包含必要套件及其相依性的 ZIP 檔案。

    • 針對私人套件，請壓縮套件的資料夾及其相依性的資料夾。
    • 針對公用套件，壓縮在上一個步驟中下載的檔案。

    注意

    • 請務必下載與 Python 引擎和沙箱運行時間平臺相容的套件（目前在 Windows 上為 3.6.5）
    • 請務必自行壓縮 .whl 檔案，而不是其父資料夾。
    • 您可以略過 .whl 已存在於基底沙盒映像中相同版本的套件檔案。

  3. 將壓縮檔上傳至成品位置中的 Blob（步驟 1）。

  4. python呼叫外掛程式。

    • external_artifacts使用名稱的屬性包和 ZIP 檔案的參考來指定 參數（Blob 的 URL，包括 SAS 令牌）。
    • 在您的內嵌 Python 程式代碼中，使用 Zipackage ZIP 檔案的名稱，從 sandbox_utils 匯入 並呼叫其 install() 方法。

範例

安裝產生假數據的Faker套件。

range ID from 1 to 3 step 1 
| extend Name=''
| evaluate python(typeof(*), ```if 1:
    from sandbox_utils import Zipackage
    Zipackage.install("Faker.zip")
    from faker import Faker
    fake = Faker()
    result = df
    for i in range(df.shape[0]):
        result.loc[i, "Name"] = fake.name()
    ```,
    external_artifacts=bag_pack('faker.zip', 'https://artifacts.blob.core.windows.net/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))
識別碼 名稱
1 加里·塔皮亞
2 艾瑪·埃文斯
3 阿什利·鮑文

相關內容

如需使用 Python 外掛程式的 UDF 函式更多範例，請參閱 Functions 連結 庫。

Python 外掛程式會使用 Python 腳本執行使用者定義函式 (UDF)。 Python 文稿會取得表格式資料做為其輸入，併產生表格式輸出。

語法

T | evaluate [ （）] [hint.remotehint.distribution == （autolocal | single | per_node）] output_schema,腳本 [ script_parameters]python( [, ,spill_to_disk])

深入瞭解 語法慣例。

參數

姓名 類型​​ 必要 描述
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 外掛程式時，請使用它。
spill_to_disk bool 指定將輸入數據表串行化至 Python 沙箱的替代方法。 若要串行化大型數據表，請將它設定為 true ，以加速串行化，並大幅降低沙箱記憶體耗用量。 預設值為 true。

保留的 Python 變數

下列變數會保留給 Kusto 查詢語言 與 Python 程式代碼之間的互動。

  • df：輸入表格式數據（上述的值 T ），做為 pandas DataFrame。
  • kargs：script_parameters自變數的值，做為 Python 字典。
  • resultpandas:P ython 腳本所建立的數據框架，其值會成為傳送至外掛程式後面 Kusto 查詢運算子的表格式數據。

啟用外掛程式

該外掛程式預設為停用。 開始之前，請在 KQL 資料庫中啟用 Python 外掛程式。

Python 沙盒映射

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

注意

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

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

範例

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

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

效能祕訣

  • 將外掛程式的輸入數據集縮減為所需的最小數量（數據行/數據列）。
    • 盡可能搭配 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

相關內容

如需使用 Python 外掛程式的 UDF 函式更多範例，請參閱 Functions 連結 庫。