Wtyczka języka Python

Artykuł
01/23/2024

Wtyczka języka Python uruchamia funkcję zdefiniowaną przez użytkownika (UDF) przy użyciu skryptu języka Python. Skrypt języka Python pobiera dane tabelaryczne jako dane wejściowe i generuje dane wyjściowe tabelaryczne. Środowisko uruchomieniowe wtyczki jest hostowane w piaskownicach uruchomionych w węzłach klastra.

Składnia

T|evaluate [hint.distribution= ()] [hint.remote= (autoper_node | | singlelocal)] python(skryptoutput_schema, [,script_parameters] [,external_artifacts][,spill_to_disk])

Dowiedz się więcej o konwencjach składniowych.

Parametry

Nazwa	Typ	Wymagane	Opis
output_schema	`string`	✔️	Literał `type` definiujący schemat wyjściowy danych tabelarycznych zwrócony przez kod języka Python. Format to: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Na przykład `typeof(col1:string, col2:long)`. Aby rozszerzyć schemat wejściowy, użyj następującej składni: `typeof(*, col1:string, col2:long)`.
Skrypt	`string`	✔️	Prawidłowy skrypt języka Python do wykonania. Aby wygenerować ciągi wielowierszowe, zobacz Porady dotyczące użycia.
script_parameters	`dynamic`		Torba właściwości par wartości nazw, które mają zostać przekazane do skryptu języka Python jako słownika zarezerwowanego `kargs` . Aby uzyskać więcej informacji, zobacz Zmienne zarezerwowane języka Python.
hint.distribution	`string`		Wskazówka dotycząca wykonywania wtyczki do dystrybucji między wieloma węzłami klastra. Wartość domyślna to `single`. `single` oznacza, że pojedyncze wystąpienie skryptu będzie uruchamiane przez całe dane zapytania. `per_node` oznacza, że jeśli zapytanie przed dystrybucją bloku języka Python, wystąpienie skryptu zostanie uruchomione w każdym węźle, na danych, które zawiera.
hint.remote	`string`		Ta wskazówka jest istotna tylko w przypadku zapytań między klastrami. Wartość domyślna to `auto`. `auto` oznacza, że serwer decyduje automatycznie, w którym klaster jest wykonywany kod języka Python. Ustawienie wartości wymusza `local` wykonywanie kodu w języku Python w klastrze lokalnym. Użyj go, jeśli wtyczka języka Python jest wyłączona w klastrze zdalnym.
external_artifacts	`dynamic`		Torba właściwości z parami nazw i adresów URL dla artefaktów, które są dostępne z magazynu w chmurze. Zobacz więcej w temacie Używanie artefaktów zewnętrznych.
spill_to_disk	`bool`		Określa alternatywną metodę serializacji tabeli wejściowej w piaskownicy języka Python. W przypadku serializacji dużych tabel ustaw ją tak, aby `true` przyspieszyć serializacji i znacznie zmniejszyć zużycie pamięci piaskownicy. Wartość domyślna to `true`.

Zarezerwowane zmienne języka Python

Następujące zmienne są zarezerwowane do interakcji między język zapytań Kusto a kodem języka Python.

df: dane tabelaryczne wejściowe (wartości T powyżej) jako ramka pandas danych.
kargs: wartość argumentu script_parameters jako słownik języka Python.
result: Ramka danych utworzona pandas przez skrypt języka Python, której wartość staje się danymi tabelarycznymi, które są wysyłane do operatora zapytania Kusto, który jest zgodny z wtyczką.

Włączanie wtyczki

Wtyczka jest domyślnie wyłączona. Przed rozpoczęciem przejrzyj listę wymagań wstępnych. Aby włączyć wtyczkę i wybrać wersję obrazu języka Python, zobacz Włączanie rozszerzeń językowych w klastrze.

Obraz piaskownicy języka Python

Aby zmienić wersję obrazu języka Python, zobacz Zmienianie obrazu rozszerzeń języka Python w klastrze.

Aby wyświetlić listę pakietów dla różnych obrazów języka Python, zobacz Dokumentacja pakietu języka Python.

Uwaga

Domyślnie wtyczka importuje numpy jako np i pandas jako pd. Opcjonalnie możesz zaimportować inne moduły zgodnie z potrzebami.
Niektóre pakiety mogą być niezgodne z ograniczeniami wymuszanymi przez piaskownicę, w której jest uruchamiana wtyczka.

Korzystanie z pozyskiwania z zasad zapytań i aktualizacji

Użyj wtyczki w zapytaniach, które są następujące:
- Definiowane jako część zasad aktualizacji, których tabela źródłowa jest pozyskiwana do korzystania z pozyskiwania danych przesyłania strumieniowego .
- Uruchom polecenie w ramach polecenia pozyskiwanego z zapytania, takiego jak .set-or-append.
Nie można użyć wtyczki w zapytaniu zdefiniowanym jako część zasad aktualizacji, których tabela źródłowa jest pozyskiwana przy użyciu pozyskiwania przesyłania strumieniowego.

Przykłady

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

Zrzut ekranu przedstawiający pokaz sinusu przedstawiający wynik zapytania.

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"})
)

File	Rozmiar
this_is_a_script	120
this_is_my_first_file	105

Porady dotyczące wydajności

Zmniejsz wejściowy zestaw danych wtyczki do minimalnej wymaganej ilości (kolumny/wiersze).
- Użyj filtrów w źródłowym zestawie danych, jeśli to możliwe, z językiem zapytań Kusto.
- Aby wykonać obliczenia w podzestawie kolumn źródłowych, należy projektować tylko te kolumny przed wywołaniem wtyczki.
Użyj hint.distribution = per_node za każdym razem, gdy logika w skry skrycie jest dystrybuowana.
- Możesz również użyć operatora partycji do partycjonowania wejściowego zestawu danych.
Użyj języka zapytań Kusto, jeśli to możliwe, aby zaimplementować logikę skryptu języka Python.

Porady dotyczące użycia

Aby wygenerować ciągi wielowierszowe zawierające skrypt języka Python w edytorze zapytań, skopiuj skrypt języka Python z ulubionego edytora języka Python (Jupyter, Visual Studio Code, PyCharm itd.), wklej go w edytorze zapytań, a następnie załącz pełny skrypt między wierszami zawierającymi trzy kolejne backticks. Na przykład:

```
python code
```
externaldata Użyj operatora , aby uzyskać zawartość skryptu przechowywanego w lokalizacji zewnętrznej, takiej jak usługa Azure Blob Storage.

Przykład

    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

Używanie artefaktów zewnętrznych

Artefakty zewnętrzne z magazynu w chmurze mogą być udostępniane dla skryptu i używane w czasie wykonywania.

Adresy URL, do których odwołuje się właściwość artefaktów zewnętrznych, muszą być następujące:

Uwzględnione w zasadach objaśnienie klastra.
W publicznie dostępnej lokalizacji lub podaj niezbędne poświadczenia, jak wyjaśniono w temacie Parametry połączenia magazynu.

Uwaga

Podczas uwierzytelniania artefaktów zewnętrznych przy użyciu tożsamości zarządzanych SandboxArtifacts należy zdefiniować użycie w zasadach tożsamości zarządzanej na poziomie klastra.

Artefakty są udostępniane dla skryptu do korzystania z lokalnego katalogu tymczasowego, .\Temp. Nazwy podane w torbie właściwości są używane jako lokalne nazwy plików. Zobacz Przykłady.

Aby uzyskać informacje dotyczące odwoływania się do pakietów zewnętrznych, zobacz Instalowanie pakietów dla wtyczki języka Python.

Odświeżanie zewnętrznej pamięci podręcznej artefaktów

Zewnętrzne pliki artefaktów używane w zapytaniach są buforowane w klastrze. Jeśli wprowadzisz aktualizacje plików w magazynie w chmurze i potrzebujesz natychmiastowej synchronizacji z klastrem, możesz użyć polecenia .clear cluster cache external-artifacts. To polecenie czyści buforowane pliki i zapewnia, że kolejne zapytania są uruchamiane z najnowszą wersją artefaktów.

Instalowanie pakietów dla wtyczki języka Python

Może być konieczne samodzielne zainstalowanie pakietów z następujących powodów:

Pakiet jest prywatny i jest twój własny.
Pakiet jest publiczny, ale nie jest uwzględniony w obrazie podstawowym wtyczki.

Zainstaluj pakiety w następujący sposób:

Wymagania wstępne

Utwórz kontener obiektów blob do hostowania pakietów, najlepiej w tym samym miejscu co klaster. Na przykład , zakładając, https://artifactswestus.blob.core.windows.net/pythonże klaster znajduje się w regionie Zachodnie stany USA.
Zmień zasady objaśnienie klastra, aby zezwolić na dostęp do tej lokalizacji.
- Ta zmiana wymaga uprawnień AllDatabasesAdmin .
- Aby na przykład włączyć dostęp do obiektu blob znajdującego się w https://artifactswestus.blob.core.windows.net/pythonlokalizacji , uruchom następujące polecenie:
```
.alter-merge cluster policy callout @'[ { "CalloutType": "sandbox_artifacts", "CalloutUriRegex": "artifactswestus\\.blob\\.core\\.windows\\.net/python/","CanCall": true } ]'
```

Instalowanie pakietów

W przypadku pakietów publicznych w narzędziu PyPi lub innych kanałach pobierz pakiet i jego zależności.
- W oknie wiersza polecenia w lokalnym środowisku Windows Python uruchom polecenie:
```
pip wheel [-w download-dir] package-name.
```
Utwórz plik zip zawierający wymagany pakiet i jego zależności.
- W przypadku pakietów prywatnych spakuj folder pakietu i foldery jego zależności.
- W przypadku pakietów publicznych spakuj pliki pobrane w poprzednim kroku.
Uwaga
- Pamiętaj, aby pobrać pakiet zgodny z aparatem języka Python i platformą środowiska uruchomieniowego piaskownicy (obecnie 3.6.5 w systemie Windows)
- Pamiętaj, aby spakować .whl same pliki, a nie folder nadrzędny.
- Możesz pominąć .whl pliki pakietów, które już istnieją z tą samą wersją w podstawowym obrazie piaskownicy.
Przekaż spakowany plik do obiektu blob w lokalizacji artefaktów (z kroku 1).
Wywołaj wtyczkę python .
- external_artifacts Określ parametr z nazwą właściwości i odwołaniem do pliku zip (adres URL obiektu blob, w tym token SAS).
- W wbudowanym kodzie python zaimportuj Zipackagesandbox_utils metodę i wywołaj jej install() metodę z nazwą pliku zip.

Przykład

Zainstaluj pakiet Faker , który generuje fałszywe dane.

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/kusto/Faker.zip?*** REPLACE WITH YOUR SAS TOKEN ***'))

ID (Identyfikator)	Nazwa
1	Gary Tapia
2	Emma Evans
3	Ashley Bowen

Aby uzyskać więcej przykładów funkcji UDF korzystających z wtyczki języka Python, zobacz bibliotekę usługi Functions.

Składnia

T|evaluate [hint.distribution= ()] [hint.remote= (auto | per_nodesinglelocal | )] python(output_schema,skrypt [,script_parameters] [,spill_to_disk])

Dowiedz się więcej o konwencjach składniowych.

Parametry

Nazwa	Typ	Wymagane	Opis
output_schema	`string`	✔️	Literał `type` definiujący schemat wyjściowy danych tabelarycznych zwracany przez kod języka Python. Format to: `typeof(`ColumnName`:`ColumnType[, ...]`)`. Na przykład `typeof(col1:string, col2:long)`. Aby rozszerzyć schemat wejściowy, użyj następującej składni: `typeof(*, col1:string, col2:long)`.
Skrypt	`string`	✔️	Prawidłowy skrypt języka Python do wykonania. Aby wygenerować ciągi wielowierszowe, zobacz Porady dotyczące użycia.
script_parameters	`dynamic`		Worek właściwości par wartości nazw, które mają zostać przekazane do skryptu języka Python jako słownika zarezerwowanego `kargs` . Aby uzyskać więcej informacji, zobacz Reserved Python variables (Zarezerwowane zmienne języka Python).
hint.distribution	`string`		Wskazówka dotycząca wykonywania wtyczki, która ma być dystrybuowana między wieloma węzłami klastra. Wartość domyślna to `single`. `single` oznacza, że pojedyncze wystąpienie skryptu zostanie uruchomione na wszystkich danych zapytania. `per_node` oznacza, że jeśli zapytanie przed dystrybucją bloku języka Python, wystąpienie skryptu zostanie uruchomione w każdym węźle, na danych, które zawiera.
hint.remote	`string`		Ta wskazówka jest istotna tylko w przypadku zapytań między klastrami. Wartość domyślna to `auto`. `auto` oznacza, że serwer decyduje automatycznie, w którym klaster jest wykonywany kod w języku Python. Ustawienie wartości w celu `local` wymuszania wykonywania kodu w języku Python w klastrze lokalnym. Użyj go, jeśli wtyczka języka Python jest wyłączona w klastrze zdalnym.
spill_to_disk	`bool`		Określa alternatywną metodę serializacji tabeli wejściowej do piaskownicy języka Python. W przypadku serializacji dużych tabel ustaw ją tak, aby `true` przyspieszyć serializacji i znacznie zmniejszyć zużycie pamięci piaskownicy. Wartość domyślna to `true`.

Zarezerwowane zmienne języka Python

Następujące zmienne są zarezerwowane do interakcji między język zapytań Kusto a kodem języka Python.

df: dane tabelaryczne wejściowe (wartości T powyżej) jako ramka pandas danych.
kargs: wartość argumentu script_parameters jako słownik języka Python.
resultpandas: Ramka danych utworzona przez skrypt języka Python, której wartość staje się danymi tabelarycznymi, które są wysyłane do operatora zapytania Kusto, który jest zgodny z wtyczką.

Włączanie wtyczki

Wtyczka jest domyślnie wyłączona. Przed rozpoczęciem włącz wtyczkę języka Python w bazie danych języka KQL.

Obraz piaskownicy języka Python

Aby wyświetlić listę pakietów dla różnych obrazów języka Python, zobacz Dokumentacja pakietu języka Python.

Uwaga

Domyślnie wtyczka importuje numpy jako np i pandas jako pd. Opcjonalnie możesz zaimportować inne moduły zgodnie z potrzebami.
Niektóre pakiety mogą być niezgodne z ograniczeniami wymuszanymi przez piaskownicę, w której jest uruchamiana wtyczka.

Używanie pozyskiwania z zasad zapytań i aktualizacji

Użyj wtyczki w zapytaniach, które są następujące:
- Zdefiniowano jako część zasad aktualizacji, których tabela źródłowa jest pozyskiwana do korzystania z pozyskiwania danych bez przesyłania strumieniowego .
- Uruchom polecenie w ramach polecenia pozyskiwanego z zapytania, takiego jak .set-or-append.
Nie można użyć wtyczki w zapytaniu zdefiniowanym jako część zasad aktualizacji, których tabela źródłowa jest pozyskiwana przy użyciu pozyskiwania danych przesyłanych strumieniowo.

Przykłady

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

Zrzut ekranu przedstawiający pokaz sinusu przedstawiający wynik zapytania.

Porady dotyczące wydajności

Zmniejsz wejściowy zestaw danych wtyczki do minimalnej wymaganej ilości (kolumny/wiersze).
- Używaj filtrów w źródłowym zestawie danych, jeśli to możliwe, z językiem zapytań kusto.
- Aby wykonać obliczenie w podzestawie kolumn źródłowych, należy projektować tylko te kolumny przed wywołaniem wtyczki.
Należy używać hint.distribution = per_node za każdym razem, gdy logika w skry skrycie jest dystrybuowana.
- Możesz również użyć operatora partycji do partycjonowania wejściowego zestawu danych.
Użyj języka zapytań Kusto, jeśli to możliwe, aby zaimplementować logikę skryptu języka Python.

Porady dotyczące użycia

Aby wygenerować ciągi wielowierszowe zawierające skrypt języka Python w edytorze zapytań, skopiuj skrypt języka Python z ulubionego edytora języka Python (Jupyter, Visual Studio Code, PyCharm itd.), wklej go w edytorze zapytań, a następnie załącz pełny skrypt między wierszami zawierającymi trzy kolejne backticks. Na przykład:

```
python code
```
externaldata Użyj operatora , aby uzyskać zawartość skryptu przechowywanego w lokalizacji zewnętrznej, takiej jak usługa Azure Blob Storage.

Przykład

    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

Aby uzyskać więcej przykładów funkcji UDF korzystających z wtyczki języka Python, zobacz bibliotekę usługi Functions.

Ta funkcja nie jest obsługiwana.

Wtyczka języka Python

Składnia

Parametry

Zarezerwowane zmienne języka Python

Włączanie wtyczki

Obraz piaskownicy języka Python

Korzystanie z pozyskiwania z zasad zapytań i aktualizacji

Przykłady

Porady dotyczące wydajności

Porady dotyczące użycia

Przykład

Używanie artefaktów zewnętrznych

Odświeżanie zewnętrznej pamięci podręcznej artefaktów

Instalowanie pakietów dla wtyczki języka Python

Wymagania wstępne

Instalowanie pakietów

Przykład

Składnia

Parametry

Zarezerwowane zmienne języka Python

Włączanie wtyczki

Obraz piaskownicy języka Python

Używanie pozyskiwania z zasad zapytań i aktualizacji

Przykłady

Porady dotyczące wydajności

Porady dotyczące użycia

Przykład

Opinia

Opinia

Dodatkowe zasoby

Wtyczka języka Python

Składnia

Parametry

Zarezerwowane zmienne języka Python

Włączanie wtyczki

Obraz piaskownicy języka Python

Korzystanie z pozyskiwania z zasad zapytań i aktualizacji

Przykłady

Porady dotyczące wydajności

Porady dotyczące użycia

Przykład

Używanie artefaktów zewnętrznych

Odświeżanie zewnętrznej pamięci podręcznej artefaktów

Instalowanie pakietów dla wtyczki języka Python

Wymagania wstępne

Instalowanie pakietów

Przykład

Zawartość pokrewna

Składnia

Parametry

Zarezerwowane zmienne języka Python

Włączanie wtyczki

Obraz piaskownicy języka Python

Używanie pozyskiwania z zasad zapytań i aktualizacji

Przykłady

Porady dotyczące wydajności

Porady dotyczące użycia

Przykład

Zawartość pokrewna

Opinia

Opinia

Dodatkowe zasoby