Schnellstartbeispiele für die Azure Storage Erweiterung in Azure Database for PostgreSQL flexiblen Server

In den folgenden Beispielen erfahren Sie, wie Sie die Azure Storage Erweiterung verwenden.

Erstellen eines Azure Storage-Kontos und Auffüllen mit Daten

Erstellen Sie ein Azure Storage-Konto. Um ein Azure Storage Konto zu erstellen, passen Sie die Werte von <resource_group>, <location>, <account_name> und <container_name> an, und führen Sie den folgenden Azure CLI Befehl aus:

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

Erstellen Sie einen BLOB-Container.

Führen Sie zum Erstellen des Blobcontainers den folgenden Azure CLI Befehl aus:
```
az storage container create --account-name $storage_account --name $blob_container -o tsv
```
Rufen Sie eine der beiden Zugriffstasten ab, die dem Speicherkonto zugewiesen sind. Stellen Sie sicher, dass Sie den Wert Ihres Zugriffsschlüssels kopieren, da Sie ihn als Argument an azure_storage.account_add in einem nachfolgenden Schritt übergeben müssen.

Führen Sie zum Abrufen der ersten der beiden Zugriffstasten den folgenden Azure CLI Befehl aus:
```
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
```

Laden Sie die Datei mit dem Datensatz herunter, der während der Beispiele verwendet wird, und laden Sie sie in Ihren BLOB-Container hoch.

Führen Sie den folgenden Azure CLI Befehl aus, um die Datei mit dem Datensatz herunterzuladen:

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

Hinweis

Sie können Container oder die darin gespeicherten Blobs für ein bestimmtes Speicherkonto auflisten, aber nur, wenn Ihrem PostgreSQL-Benutzer oder Ihrer Rolle die Berechtigung für den Verweis auf dieses Speicherkonto erteilt wird, indem Sie azure_storage.account_user_add verwenden. Mitgliedern der azure_storage_admin Rolle wird diese Berechtigung für alle Azure Storage Konten gewährt, die mithilfe von azure_storage.account_add hinzugefügt werden. Standardmäßig werden nur Mitglieder der azure_pg_adminazure_storage_admin Rolle gewährt.

Erstellen einer Tabelle zum Laden von Daten

Erstellen Sie die Tabelle, in die Sie den Inhalt der Dateien importieren, die Sie in das Speicherkonto hochgeladen haben. Stellen Sie dazu eine Verbindung mit Ihrer Instanz von Azure Database for PostgreSQL flexiblen Server her, indem Sie PostgreSQL für Visual Studio Code (Vorschau),psql, PgAdmin oder den Client Ihrer Vorliebe verwenden, und führen Sie die folgende Anweisung aus:

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

Vorbereiten der Erweiterung für die Verwendung

Bevor Sie fortfahren, stellen Sie sicher, dass Sie:

Hinzufügen des Zugriffsschlüssels des Speicherkontos

In diesem Beispiel wird gezeigt, wie Sie einem Speicherkonto einen Verweis zusammen mit dem Zugriffsschlüssel dieses Speicherkontos hinzufügen. Um auf den Inhalt des Speicherkontos zuzugreifen, benötigt die azure_storage Erweiterung in Ihrer Instanz von Azure Database for PostgreSQL flexiblen Server den Zugriffsschlüssel.

Legen Sie <account_name> den Namen Ihres Speicherkontos fest. Wenn Sie die vorherigen Skripts verwendet haben, sollte dieser Wert mit dem Wert übereinstimmen, den Sie für die storage_account Umgebungsvariable in diesen Skripts festgelegt haben.

Legen Sie <access_key> diesen Wert fest, den Sie aus Ihrem Speicherkonto abgerufen haben.

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

Tipp

Um den Namen des Speicherkontos und eine seiner Zugriffstasten aus dem Azure-Portal abzurufen, suchen Sie nach Ihrem Speicherkonto. Wählen Sie im Ressourcenmenü Die Zugriffstasten aus. Kopieren Sie den Namen des Speicherkontos , und kopieren Sie den Schlüssel aus dem Abschnitt "key1 ". Sie müssen zuerst neben der Taste " Anzeigen" auswählen.

Gewähren des Zugriffs auf einen Benutzer oder eine Rolle in der Azure Blob Storage-Referenz

In diesem Beispiel wird gezeigt, wie Der Zugriff auf einen Benutzer oder eine Rolle mit dem Namen <regular_user>gewährt wird, sodass der PostgreSQL-Benutzer die azure_storage Erweiterung verwenden kann, um auf die blobs zuzugreifen, die in Containern gespeichert sind, die von dem bezeichneten Azure Speicherkonto gehostet werden.

Legen Sie <regular_user> den Namen eines vorhandenen Benutzers oder einer vorhandenen Rolle fest.

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

Auflisten aller Blobs in einem Container

In diesem Beispiel wird gezeigt, wie alle vorhandenen Blobs im Container <container_name> des Speicherkontos <account_name>aufgeführt werden.

Legen Sie <container_name> den Namen ihres BLOB-Containers fest. Wenn Sie die vorherigen Skripts verwendet haben, sollte dieser Wert mit dem Wert übereinstimmen, den Sie für die blob_container Umgebungsvariable in diesen Skripts festgelegt haben.

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

Auflisten von Blobs mit einem bestimmten Namenspräfix

In diesem Beispiel wird gezeigt, wie alle vorhandenen Blobs im Container <container_name> des Speicherkontos <account_name>aufgeführt werden, deren BLOB-Name beginnt <blob_name_prefix>.

Legen Sie <blob_name_prefix> auf das Präfix fest, das die Blobs aufzählen sollen, die in ihre Namen aufgenommen werden sollen. Wenn Sie alle Blobs zurückgeben möchten, legen Sie diesen Parameter auf eine leere Zeichenfolge fest, oder geben Sie keinen Wert für diesen Parameter an. In diesem Fall wird der Wert standardmäßig auf eine leere Zeichenfolge festgelegt.

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

Alternativ können Sie die folgende Syntax verwenden:

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

Importieren von Daten mithilfe einer COPY FROM-Anweisung

Das folgende Beispiel zeigt, wie Daten aus einem Blob storage_extension_sample.parquet importiert werden, der sich im Blobcontainer <container_name> im Azure Storage-Konto <account_name>befindet. Der Import verwendet den COPY Befehl:

Erstellen Sie eine Tabelle, die dem Schema der Quelldatei entspricht.

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

Verwenden Sie eine COPY Anweisung, um Daten in die Zieltabelle zu kopieren. Das Format wird als Parkett aus der Erweiterung der Datei abgeleitet.

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

Verwenden Sie eine COPY Anweisung, um Daten in die Zieltabelle zu kopieren. Da das Codierungsformat nicht von der Dateierweiterung abgeleitet werden kann, geben Sie es explizit mithilfe der FORMAT Option an.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
Verwenden Sie eine COPY Anweisung, um Daten in die Zieltabelle zu kopieren. Das Codierungsformat kann aus der Dateierweiterung abgeleitet werden. Sie müssen jedoch explizit das Vorhandensein von Spaltenüberschriften in der ersten Zeile mithilfe der HEADERS Option konfigurieren.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Führen Sie die folgende SELECT Anweisung aus, um zu bestätigen, dass die Daten in die Tabelle geladen werden.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Exportieren von Daten mithilfe einer COPY TO-Anweisung

In den folgenden Beispielen wird gezeigt, wie Daten aus einer Tabelle exportiert werden, die in mehrere Blobs mit unterschiedlichen Namen und Merkmalen benannt sample_data ist, z. B. deren Codierungsformat. Alle Blobs befinden sich im BLOB-Container <container_name> im Azure Storage Konto<account_name>. Verwenden Sie den COPY Befehl zum Exportieren der Daten:

Erstellen Sie eine Tabelle, die dem Schema der Quelldatei entspricht.

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

Erstellen Sie eine Tabelle, die dem Schema der Quelldatei entspricht.

Verwenden Sie eine COPY Anweisung, um Daten aus der Zieltabelle zu kopieren. Geben Sie an, dass das Codierungsformat Überparkett sein muss.

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

Verwenden Sie eine COPY Anweisung, um Daten aus der Zieltabelle zu kopieren. Geben Sie an, dass das Codierungsformat CSV sein muss und die erste Zeile der resultierenden Datei Spaltenüberschriften enthält.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Führen Sie die folgende SELECT Anweisung aus, um zu bestätigen, dass das Blob im Speicherkonto vorhanden ist.

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

Lesen von Inhalten aus einem Blob

Die blob_get Funktion ruft den Inhalt eines bestimmten Blobs im referenzierbaren Container <container_name> des <account_name> Speichers ab. Um die Daten zu blob_get analysieren, übergeben Sie einen Wert im Formular NULL::table_name, wobei table_name sich auf eine Tabelle bezieht, deren Schema mit dem des gelesenen Blobs übereinstimmt. Im Beispiel bezieht es sich auf die Tabelle, die sample_data Sie am Anfang erstellt haben.

Legen Sie <blob_name> den vollständigen Pfad des Blobs fest, dessen Inhalt Sie lesen möchten.

In diesem Fall wird der Decoder, der das Blob analysiert, von der .parquet Dateierweiterung abgeleitet.

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

Alternativ können Sie das Schema des Ergebnisses explizit definieren, indem Sie die AS Klausel nach der blob_get-Funktion verwenden.

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;

Lesen, Filtern und Ändern von Inhalten aus einem Blob

In diesem Beispiel wird gezeigt, wie Sie den aus dem Blob importierten Inhalt filtern und ändern können, bevor Sie ihn in eine SQL-Tabelle laden.

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;

Lesen von Inhalten aus datei mit benutzerdefinierten Optionen (Kopfzeilen, Spaltentrennzeichen, Escapezeichen)

In diesem Beispiel wird gezeigt, wie Benutzerdefinierte Trennzeichen und Escapezeichen verwendet werden, indem das Ergebnis von options_copy an das options Argument übergeben wird.

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

Verwenden der Decoderoption

In diesem Beispiel wird die Verwendung der decoder Option veranschaulicht. Wenn Sie die Decoderoption nicht einschließen, leitet das System sie von der Erweiterung der Datei ab. Wenn der Dateiname nicht über eine Erweiterung verfügt oder die Dateinamenerweiterung nicht dem Decoder entspricht, den das System benötigt, um den Inhalt der Datei ordnungsgemäß zu analysieren, können Sie das Decoderargument explizit übergeben.

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

Berechnen von Aggregationen über den Inhalt eines Blobs

In diesem Beispiel wird gezeigt, wie Aggregationsvorgänge über Informationen ausgeführt werden, die in einem BLOB-Container gespeichert sind, ohne dass der Inhalt des Blobs in PostgreSQL-Tabellen importiert werden muss.

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;

Schreiben von Inhalten in ein Blob

Die blob_put Funktion verfasst den Inhalt eines bestimmten Blobs (sample_data_copy.parquet in diesem Fall), und lädt ihn in den referenzierbaren Container <container_name> des <account_name> Speichers hoch. In diesem Beispiel wird blob_get eine Gruppe von fünf Zeilen erstellt, die dann an die blob_put Aggregatfunktion übergeben werden, die sie als BLOB sample_data_copy.parquethochlädt.

Das Codierungsformat wird basierend auf der Dateierweiterung .parquetals Parkett abgeleitet.

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;

Das Codierungsformat wird basierend auf der Dateierweiterung .csvals CSV abgeleitet.

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;

Das Codierungsformat kann nicht abgeleitet werden, da die Datei nicht über eine Dateierweiterung verfügt, sodass es explizit als parquetkonfiguriert ist. Außerdem wird der Komprimierungsalgorithmus auf .zstd

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;

Auflisten aller Verweise auf Azure-Speicherkonten

In diesem Beispiel wird gezeigt, wie Sie herausfinden, auf welche Azure Speicherkonten die azure_storage Erweiterung in dieser Datenbank verweisen kann, zusammen mit dem Typ der Authentifizierung, die für den Zugriff auf jedes Speicherkonto verwendet wird. Außerdem wird angezeigt, welche Benutzer oder Rollen über die Funktion azure_storage.account_user_add auf dieses Azure Speicherkonto über die von der Erweiterung bereitgestellte Funktionalität zugreifen können.

SELECT * FROM azure_storage.account_list();

Widerrufen des Zugriffs von einem Benutzer oder einer Rolle in der Azure Blob Storage-Referenz

In diesem Beispiel wird gezeigt, wie Der Zugriff von einem Benutzer oder einer Rolle mit dem Namen <regular_user>widerrufen wird, damit der PostgreSQL-Benutzer die azure_storage Erweiterung nicht für den Zugriff auf die blobs verwenden kann, die in Containern gespeichert sind, die vom referenziert Azure Speicherkonto gehostet werden.