Przykłady szybkiego startu dla rozszerzenia Azure Storage na serwerze elastycznym Azure Database for PostgreSQL

Poniższe przykłady pomagają dowiedzieć się, jak używać rozszerzenia Azure Storage.

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

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

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ące polecenie Azure CLI:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Uzyskaj jeden z dwóch kluczy dostępu przypisanych do konta magazynu. Upewnij się, że skopiujesz wartość klucza dostępu, ponieważ musisz przekazać go jako argument, aby azure_storage.account_add w kolejnym kroku.

Aby uzyskać pierwszy z dwóch kluczy dostępu, uruchom następujące polecenie Azure CLI:
```
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 Azure CLI:

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 Azure Storage, które są dodawane 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 mają być ładowane dane

Utwórz tabelę, w której zaimportujesz zawartość plików przekazanych do konta magazynu. W tym celu nawiąż połączenie z wystąpieniem serwera elastycznego Azure Database for PostgreSQL przy użyciu bazy danych PostgreSQL dla 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. Aby uzyskać dostęp do zawartości konta magazynu, azure_storage rozszerzenie w twoim wystąpieniu serwera elastycznego Azure Database for PostgreSQL wymaga klucza dostępu.

Ustaw <account_name> nazwę konta magazynu. Jeśli użyto poprzednich skryptów, ta wartość powinna być zgodna z wartością ustawioną dla zmiennej środowiskowej storage_account w tych skryptach.

Ustaw <access_key> wartość pobraną z konta magazynu.

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

Wskazówka

Aby pobrać nazwę konta magazynu i jeden z jego kluczy dostępu z portalu Azure, wyszukaj konto magazynu. W menu zasobów wybierz pozycję Klucze dostępu. Skopiuj nazwę konta magazynu i skopiuj klucz z sekcji key1 . 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 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 magazynu Azure.

Ustaw <regular_user> 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.

Ustaw <container_name> nazwę kontenera obiektów blob. Jeśli użyto poprzednich skryptów, ta wartość powinna być zgodna z wartością ustawioną dla zmiennej środowiskowej 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>.

Ustaw <blob_name_prefix> wartość prefiksu, który ma zostać wyliczony do uwzględnienia w nazwach obiektów blob. Jeśli chcesz zwrócić wszystkie obiekty blob, ustaw ten parametr na pusty ciąg lub nie określ 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, jak zaimportować dane z obiektu blob o nazwie storage_extension_sample.parquet znajdującego się w kontenerze <container_name> obiektów blob na koncie <account_name>Azure Storage . Import używa 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 wnioskowany 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, określ go jawnie przy użyciu 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. Należy jednak jawnie skonfigurować obecność nagłówków kolumn w pierwszym wierszu przy użyciu 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, jak wyeksportować dane z tabeli o nazwie sample_data do wielu obiektów blob o różnych nazwach i cechach, takich jak ich format kodowania. Wszystkie obiekty blob znajdują się w kontenerze <container_name> obiektów blob na koncie <account_name>Azure Storage . Użyj polecenia , COPY aby wyeksportować dane:

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
);

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

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 ułatwić blob_get analizowanie danych, przekaż 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.

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

W takim przypadku dekoder, który analizuje obiekt 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, używając 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, jak można filtrować i modyfikować zawartość zaimportowaną 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 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 decoder pokazano, jak używać opcji . Jeśli nie dołączysz opcji dekodera, system wywnioskuje go z rozszerzenia pliku. Jeśli nazwa pliku nie ma rozszerzenia lub jeśli rozszerzenie nazwy pliku nie odpowiada dekoderowi, który system musi prawidłowo przeanalizować zawartość pliku, możesz 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 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 utworzenia zestawu pięciu wierszy, które są następnie 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 dowiedzieć się, które Azure kontach azure_storage magazynu, do których 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. Pokazuje również, którzy użytkownicy lub role mają przyznane uprawnienia za pośrednictwem funkcji azure_storage.account_user_add, aby uzyskać dostęp do tego konta magazynu Azure 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 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 magazynu Azure.