Wtyczka języka Python

Artykuł
07/03/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 = (autosingle | per_nodelocal | )] python(skrypt output_schema, [, script_parameters] [, external_artifacts][, spill_to_disk])

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	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 Reserved Python variables (Zmienne zarezerwowane języka Python).
hint.distribution	`string`		Wskazówka dotycząca wykonywania wtyczki do dystrybucji między wieloma węzłami klastra. Domyślna wartość 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. Domyślna wartość 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`		Worek właściwości i pary 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.
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 przejrzyj listę wymagań wstępnych. Aby włączyć wtyczkę i wybrać wersję obrazu języka Python, zobacz Włączanie rozszerzeń języka 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.

Używanie pozyskiwania z zasad zapytań i aktualizacji

Użyj wtyczki w zapytaniach, które są następujące:
- Zdefiniowane jako część zasad aktualizacji, których tabela źródłowa jest pozyskiwana do korzystania z pozyskiwania nieprzesył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"})
)

Plik	Rozmiar
this_is_a_script	120
this_is_my_first_file	105

Wskazówki 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ć obliczenie w podzestawie kolumn źródłowych, należy projektować tylko te kolumny przed wywołaniem wtyczki.
Używaj hint.distribution = per_node za każdym razem, gdy logika w skry skryscie jest dystrybuowana.
- Możesz również użyć operatora partycji do partycjonowania wejściowego zestawu danych.
Jeśli to możliwe, użyj języka zapytań Kusto, 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 ująć 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 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 wymagasz 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 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 języku PyPi lub innych kanałach pobierz pakiet i jego zależności.
- W oknie narzędzia cmd 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 dla 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 języka Python zaimportuj Zipackage sandbox_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 ***'))

IDENTYFIKATOR	Nazwisko
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 = (autosingle | localper_node | )] python(skrypt output_schema, [, script_parameters] [, spill_to_disk])

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	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 Reserved Python variables (Zmienne zarezerwowane języka Python).
hint.distribution	`string`		Wskazówka dotycząca wykonywania wtyczki do dystrybucji między wieloma węzłami klastra. Domyślna wartość 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. Domyślna wartość 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.
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.
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:
- Zdefiniowane jako część zasad aktualizacji, których tabela źródłowa jest pozyskiwana do korzystania z pozyskiwania nieprzesył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.

Wskazówki 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ć obliczenie w podzestawie kolumn źródłowych, należy projektować tylko te kolumny przed wywołaniem wtyczki.
Używaj hint.distribution = per_node za każdym razem, gdy logika w skry skryscie jest dystrybuowana.
- Możesz również użyć operatora partycji do partycjonowania wejściowego zestawu danych.
Jeśli to możliwe, użyj języka zapytań Kusto, 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 ująć 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.

Udostępnij za pośrednictwem

Wtyczka języka Python

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

Wskazówki 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

Wskazówki dotyczące wydajności

Porady dotyczące użycia

Przykład

Opinia

Opinia

Dodatkowe zasoby

Udostępnij za pośrednictwem

Wtyczka języka Python

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

Wskazówki 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

Powiązana zawartość

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

Wskazówki dotyczące wydajności

Porady dotyczące użycia

Przykład

Powiązana zawartość

Opinia

Opinia

Dodatkowe zasoby