Przykłady szybkiego startu dla rozszerzenia usługi Azure Storage w usłudze Azure Database for PostgreSQL

Poniżej znajduje się lista przykładów, które pomogą Ci dowiedzieć się, jak używać rozszerzenia usługi Azure Storage.

Tworzenie konta usługi Azure Storage i wypełnianie go danymi

Tworzenie konta usługi Azure Storage. Aby utworzyć konto usługi Azure Storage, jeśli jeszcze go nie masz, dostosuj wartości <resource_group>, <location>, <account_name>i <container_name>uruchom następujące polecenie interfejsu wiersza polecenia platformy Azure:

random_suffix=$(tr -dc 'a-z0-9' </dev/urandom | head -c8)
resource_group="resource-group-$random_suffix"
location="eastus2"
storage_account="storageaccount$random_suffix"
blob_container="container-$random_suffix"
az group create --name $resource_group --location $location
az storage account create --resource-group $resource_group --name $storage_account --location $location --sku Standard_LRS --kind BlobStorage --public-network-access enabled --access-tier hot
echo "Take note of the storage account name, which you'll have to replace in subsequent examples, whenever you find a reference to <account_name>:"
echo $storage_account
echo "Take note of the container name, which you'll have to replace in subsequent examples, whenever you find a reference to <container_name>:"
echo $blob_container

Utwórz kontener obiektów blob. Aby utworzyć kontener obiektów blob, uruchom następujący interfejs wiersza polecenia platformy Azure:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Pobierz jeden z dwóch kluczy dostępu przypisanych do konta magazynu. Upewnij się, że skopiujesz wartość access_key, ponieważ musisz przekazać ją jako argument, aby azure_storage.account_add w kolejnym kroku. Aby pobrać pierwszy z dwóch kluczy dostępu, uruchom następujące polecenie interfejsu wiersza polecenia platformy Azure:
```
access_key=$(az storage account keys list --resource-group $resource_group --account-name $storage_account --query [0].value)
echo "Following is the value of your access key:"
echo $access_key
```

Pobierz plik z zestawem danych używanym podczas przykładów i przekaż go do kontenera obiektów blob. Aby pobrać plik z zestawem danych, uruchom następujące polecenie interfejsu wiersza polecenia platformy Azure:

mkdir --parents azure_storage_examples
cd azure_storage_examples
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.parquet
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.parquet" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/parquet_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "parquet_without_extension" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/storage_extension_sample.csv
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "storage_extension_sample.csv" --account-key $access_key --overwrite --output none --only-show-errors
curl -L -O https://github.com/Azure-Samples/azure-postgresql-storage-extension/raw/main/csv_without_extension
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "csv_without_extension" --account-key $access_key --overwrite --output none --only-show-errors

Uwaga / Notatka

Możesz wyświetlić listę kontenerów lub obiektów blob przechowywanych w nich dla określonego konta magazynu, ale tylko wtedy, gdy użytkownik lub rola PostgreSQL ma uprawnienie do odwołania do tego konta magazynu przy użyciu polecenia azure_storage.account_user_add. azure_storage_admin Członkowie roli otrzymują to uprawnienie dla wszystkich kont usługi Azure Storage, które zostały dodane przy użyciu azure_storage.account_add. Domyślnie tylko członkowie mają azure_pg_admin przypisaną azure_storage_admin rolę.

Tworzenie tabeli, w której są ładowane dane

Utwórzmy tabelę, do której zaimportujemy zawartość plików przekazanych do konta magazynu. W tym celu nawiąż połączenie z wystąpieniem serwera elastycznego usługi Azure Database for PostgreSQL za pomocą programu PostgreSQL dla programu Visual Studio Code (wersja zapoznawcza),psql, PgAdmin lub klienta preferencji i wykonaj następującą instrukcję:

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

Przygotowywanie rozszerzenia do użycia

Przed kontynuowaniem upewnij się, że:

Dodawanie klucza dostępu konta magazynu

W tym przykładzie pokazano, jak dodać odwołanie do konta magazynu wraz z kluczem dostępu tego konta magazynu, które jest wymagane do uzyskania dostępu do jego zawartości za pośrednictwem funkcji udostępnionych przez azure_storage rozszerzenie w wystąpieniu serwera elastycznego usługi Azure Database for PostgreSQL.

<account_name> musi być ustawiona na nazwę konta magazynu. Jeśli użyto poprzednich skryptów, ta wartość powinna być zgodna z dowolną wartością ustawioną na zmienną środowiskową storage_account w tych skryptach.

<access_key> Podobnie należy ustawić wartość pobraną z konta magazynu.

SELECT azure_storage.account_add('<account_name>', '<access_key>');

Wskazówka

Jeśli chcesz pobrać nazwę konta magazynu i jeden z jego kluczy dostępu z witryny Azure Portal, wyszukaj konto magazynu, w menu zasobów wybierz pozycję Klucze dostępu, skopiuj nazwę konta magazynu i skopiuj sekcję Klucz z klucza1 (musisz najpierw wybrać pozycję Pokaż obok klucza).

Udzielanie dostępu użytkownikowi lub roli w dokumentacji usługi Azure Blob Storage

W tym przykładzie pokazano, jak udzielić dostępu użytkownikowi lub roli o nazwie <regular_user>, aby taki użytkownik PostgreSQL mógł użyć azure_storage rozszerzenia w celu uzyskania dostępu do obiektów blob przechowywanych w kontenerach hostowanych przez określone konto usługi Azure Storage.

<regular_user> musi być ustawiona na nazwę istniejącego użytkownika lub roli.

SELECT * FROM azure_storage.account_user_add('<account_name>', '<regular_user>');

Wyświetlanie listy wszystkich obiektów blob w kontenerze

W tym przykładzie pokazano, jak wyświetlić listę wszystkich istniejących obiektów blob wewnątrz kontenera <container_name> konta <account_name>magazynu .

<container_name> musi być ustawiona na nazwę kontenera obiektów blob. Jeśli użyto poprzednich skryptów, ta wartość powinna być zgodna z dowolną wartością ustawioną na zmienną środowiskową blob_container w tych skryptach.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>');

Wyświetlanie listy obiektów blob z określonym prefiksem nazwy

W tym przykładzie pokazano, jak wyświetlić listę wszystkich istniejących obiektów blob wewnątrz kontenera <container_name> konta <account_name>magazynu , którego nazwa obiektu blob zaczyna się od <blob_name_prefix>.

<blob_name_prefix> należy ustawić na dowolny prefiks, który ma zostać uwzględniony w nazwach obiektów blob. Jeśli chcesz zwrócić wszystkie obiekty blob, możesz ustawić ten parametr na pusty ciąg lub nawet nie określić wartości dla tego parametru, w takim przypadku wartość domyślna to pusty ciąg.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>','<blob_name_prefix>');

Alternatywnie można użyć następującej składni:

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>') WHERE path LIKE '<blob_name_prefix>%';

Importowanie danych przy użyciu instrukcji COPY FROM

W poniższym przykładzie pokazano importowanie danych z obiektu blob o nazwie storage_extension_sample.parquet , który znajduje się w kontenerze <container_name> obiektów blob na koncie <account_name>usługi Azure Storage , za pomocą COPY polecenia :

Utwórz tabelę zgodną ze schematem pliku źródłowego:

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

COPY Użyj instrukcji , aby skopiować dane do tabeli docelowej. Format jest wywnioskowany jako Parquet z rozszerzenia pliku.

TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.parquet';

COPY Użyj instrukcji , aby skopiować dane do tabeli docelowej. Ponieważ nie można wywnioskować formatu kodowania z rozszerzenia pliku, jest on jawnie określony za pośrednictwem FORMAT opcji .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
COPY Użyj instrukcji , aby skopiować dane do tabeli docelowej. Format kodowania można wywnioskować z rozszerzenia pliku. Jednak obecność nagłówków kolumn w pierwszym wierszu musi być jawnie skonfigurowana za pośrednictwem HEADERS opcji.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Wykonaj następującą SELECT instrukcję, aby potwierdzić, że dane zostały załadowane do tabeli.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Eksportowanie danych przy użyciu instrukcji COPY TO

W poniższych przykładach pokazano eksportowanie danych z tabeli o nazwie sample_data, do wielu obiektów blob o różnych nazwach i cech, takich jak ich format kodowania, z których wszystkie znajdują się w kontenerze <container_name> obiektów blob na koncie <account_name>usługi Azure Storage , za pomocą COPY polecenia :

Utwórz tabelę zgodną ze schematem pliku źródłowego:

CREATE TABLE IF NOT EXISTS sample_data (
    id BIGINT PRIMARY KEY,
    sample_text TEXT,
    sample_integer INTEGER,
    sample_timestamp TIMESTAMP
);

Załaduj dane do tabeli. Uruchom instrukcje INSERT, aby wypełnić je kilkoma syntetycznymi wierszami lub użyj przykładu import danych przy użyciu przykładu instrukcji COPY FROM, aby wypełnić je zawartością przykładowego zestawu danych.

COPY Użyj instrukcji , aby skopiować dane z tabeli docelowej. Określ, że format kodowania musi być parquet.

COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.parquet'
WITH (FORMAT 'parquet');

COPY Użyj instrukcji , aby skopiować dane z tabeli docelowej. Określ, że format kodowania musi mieć format CSV, a pierwszy wiersz wynikowego pliku zawiera nagłówki kolumn.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Wykonaj następującą SELECT instrukcję, aby potwierdzić, że obiekt blob istnieje na koncie magazynu.

SELECT * FROM azure_storage.blob_list('<account_name>','<container_name>') WHERE path LIKE 'storage_extension_sample_exported%';

Odczytywanie zawartości z obiektu blob

Funkcja blob_get pobiera zawartość jednego określonego obiektu blob w określonym kontenerze <container_name><account_name> magazynu. Aby blob_get dowiedzieć się, jak analizować dane, można przekazać wartość w formularzu NULL::table_name, gdzie table_name odwołuje się do tabeli, której schemat pasuje do odczytywanego obiektu blob. W tym przykładzie odwołuje się ona do tabeli utworzonej sample_data na samym początku.

<blob_name> powinien być ustawiony na pełną ścieżkę obiektu blob, którego zawartość chcesz odczytać.

W tym przypadku dekoder, który musi być używany do analizowania obiektu blob, jest wnioskowany z .parquet rozszerzenia pliku.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
LIMIT 5;

Alternatywnie można jawnie zdefiniować schemat wyniku przy użyciu AS klauzuli po funkcji blob_get .

SELECT * FROM azure_storage.blob_get('<account_name>','<container_name>','storage_extension_sample.parquet')
AS res (
        id BIGINT PRIMARY KEY,
        sample_text TEXT,
        sample_integer INTEGER,
        sample_timestamp TIMESTAMP)
LIMIT 5;

Odczytywanie, filtrowanie i modyfikowanie zawartości odczytywanej z obiektu blob

W tym przykładzie pokazano możliwość filtrowania i modyfikowania zawartości importowanej z obiektu blob przed załadowaniem jej do tabeli SQL.

SELECT concat('P-',id::text) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
WHERE sample_integer=780
LIMIT 5;

Odczytywanie zawartości z pliku przy użyciu opcji niestandardowych (nagłówki, ograniczniki kolumn, znaki ucieczki)

W tym przykładzie pokazano, jak można używać separatorów niestandardowych i znaków ucieczki, przekazując wynik options_copy do argumentu options .

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.csv'
        ,NULL::sample_data
        ,options := azure_storage.options_csv_get(header := 'true')
        );

Użyj opcji dekodera

W tym przykładzie pokazano użycie decoder opcji. Gdy opcja dekodera nie jest obecna, jest ona wnioskowana z rozszerzenia pliku. Ale jeśli nazwa pliku nie ma rozszerzenia lub gdy to rozszerzenie nazwy pliku nie odpowiada temu, który jest skojarzony z dekoderem, który musi być używany do prawidłowego analizowania zawartości pliku, można jawnie przekazać argument dekodera.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'parquet_without_extension'
        , NULL::sample_data
        , decoder := 'parquet')
LIMIT 5;

Agregacje obliczeniowe dotyczące zawartości obiektu blob

W tym przykładzie pokazano, jak można wykonywać operacje agregacji na informacjach przechowywanych w kontenerze obiektów blob bez konieczności importowania zawartości obiektu blob do tabel PostgreSQL.

SELECT sample_integer, COUNT(*) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'storage_extension_sample.parquet'
        , NULL::sample_data)
GROUP BY sample_integer
ORDER BY 2 DESC
LIMIT 5;

Zapisywanie zawartości w obiekcie blob

Funkcja blob_put komponuje zawartość jednego określonego obiektu blob (sample_data_copy.parquet w tym przypadku) i przekazuje ją do określonego kontenera <container_name><account_name> magazynu. W tym przykładzie użyto blob_get metody do skonstruowania zestawu pięciu wierszy, które następnie są przekazywane do blob_put funkcji agregującej, która przekazuje je jako obiekt blob o nazwie sample_data_copy.parquet.

Format kodowania jest wnioskowany jako parquet na podstawie rozszerzenia .parquetpliku .

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.parquet'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

Format kodowania jest wywnioskowany jako CSV na podstawie rozszerzenia .csvpliku .

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_data_copy.csv'
        , top_5_sample_data)
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

Nie można wywnioskować formatu kodowania, ponieważ plik nie ma rozszerzenia pliku, dlatego jest jawnie skonfigurowany jako parquet. Ponadto algorytm kompresji jest ustawiony na zstdwartość .

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'sample_parquet_data_copy_without_extension_with_zstd_compression'
        , top_5_sample_data
        ,'parquet'
        ,'zstd')
FROM (SELECT * FROM sample_data LIMIT 5) AS top_5_sample_data;

Wyświetlanie listy wszystkich odwołań do kont usługi Azure Storage

W tym przykładzie pokazano, w jaki sposób można dowiedzieć się, do których kont azure_storage usługi Azure Storage może się odwoływać rozszerzenie w tej bazie danych, wraz z typem uwierzytelniania używanego do uzyskiwania dostępu do poszczególnych kont magazynu oraz do których użytkowników lub ról udzielono uprawnień za pośrednictwem funkcji azure_storage.account_user_add , aby uzyskać dostęp do tego konta usługi Azure Storage za pośrednictwem funkcji udostępnianych przez rozszerzenie.

SELECT * FROM azure_storage.account_list();

Odwoływanie dostępu od użytkownika lub roli w dokumentacji usługi Azure Blob Storage

W tym przykładzie pokazano, jak odwołać dostęp z użytkownika lub roli o nazwie <regular_user>, aby taki użytkownik PostgreSQL nie mógł użyć azure_storage rozszerzenia w celu uzyskania dostępu do obiektów blob przechowywanych w kontenerach hostowanych przez określone konto usługi Azure Storage.