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

Im Folgenden finden Sie eine Liste von Beispielen, die Ihnen helfen, zu erfahren, wie Sie die Azure Storage-Erweiterung verwenden.

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

Erstellen Sie ein Azure Storage-Konto. Wenn Sie noch kein Azure Storage-Konto erstellen möchten, passen Sie die Werte von <resource_group>, , <location>, <account_name>und , und <container_name>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 BLOB-Containers die folgende Azure CLI 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 Ihrer access_key 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 Dataset 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 mit azure_storage.account_add hinzugefügt wurden. Standardmäßig werden nur Mitglieder der azure_pg_adminazure_storage_admin Rolle gewährt.

Erstellen einer Tabelle, in der Daten geladen werden

Erstellen wir nun die Tabelle, in die wir den Inhalt der Dateien importieren, die wir in das Speicherkonto hochgeladen haben. Stellen Sie dazu eine Verbindung mit Ihrer Instanz von Azure Database for PostgreSQL flexiblen Server mithilfe von PostgreSQL für Visual Studio Code (Preview), psql, PgAdmin oder dem Client Ihrer Einstellung her, 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 veranschaulicht, wie Sie einem Speicherkonto einen Verweis hinzufügen, zusammen mit dem Zugriffsschlüssel dieses Speicherkontos, das für den Zugriff auf seine Inhalte über die durch die azure_storage Erweiterung in Ihrer Instanz von Azure Database für PostgreSQL flexible Server bereitgestellte Funktionalität erforderlich ist.

<account_name> muss auf den Namen Ihres Speicherkontos festgelegt werden. Wenn Sie die vorherigen Skripts verwendet haben, sollte dieser Wert mit dem Wert übereinstimmen, den Sie auf die Umgebungsvariable storage_account in diesen Skripts festlegen.

Ebenso muss auf den Wert festgelegt werden, <access_key> den Sie aus Ihrem Speicherkonto abgerufen haben.

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

Tipp

Wenn Sie den Namen des Speicherkontos und eine seiner Zugriffstasten aus dem Azure-Portal abrufen möchten, suchen Sie im Ressourcenmenü Zugriffstasten, kopieren Sie den Namen des Speicherkontos , und kopieren Sie den Schlüssel aus dem Abschnitt "key1 " (Sie müssen zuerst neben dem Schlüssel anzeigen auswählen).

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

In diesem Beispiel wird veranschaulicht, wie Der Zugriff auf einen Benutzer oder eine Rolle mit dem Namen <regular_user>gewährt wird, damit ein solcher PostgreSQL-Benutzer die azure_storage Erweiterung verwenden kann, um auf die blobs zuzugreifen, die in Containern gespeichert sind, die vom genannten Azure-Speicherkonto gehostet werden.

<regular_user> muss auf den Namen eines vorhandenen Benutzers oder einer vorhandenen Rolle festgelegt werden.

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

Auflisten aller Blobs in einem Container

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

<container_name> muss auf den Namen Ihres BLOB-Containers festgelegt werden. Wenn Sie die vorherigen Skripts verwendet haben, sollte dieser Wert mit dem Wert übereinstimmen, den Sie auf die umgebungsvariable blob_container in diesen Skripts festlegen.

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

Auflisten von Blobs mit einem bestimmten Namenspräfix

In diesem Beispiel wird veranschaulicht, wie alle vorhandenen Blobs im Container <container_name> des Speicherkontos <account_name>aufgeführt werden, deren Blobname mit <blob_name_prefix>.

<blob_name_prefix> sollte auf das Präfix festgelegt werden, das die Blobs in ihre Namen aufnehmen sollen. Wenn Sie alle Blobs zurückgeben möchten, können Sie diesen Parameter auf eine leere Zeichenfolge festlegen oder keinen Wert für diesen Parameter angeben. 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 den Import von Daten aus einem Blob, der sich storage_extension_sample.parquet im BLOB-Container <container_name> im Azure Storage-Konto <account_name>befindet, über 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, wird es explizit über die FORMAT Option angegeben.
```
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. Das Vorhandensein von Spaltenüberschriften in der ersten Zeile muss jedoch explizit über HEADERS die Option konfiguriert werden.
```
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

Die folgenden Beispiele zeigen den Export von Daten aus einer Tabelle, die aufgerufen wird sample_data, in mehrere Blobs mit unterschiedlichen Namen und Merkmalen wie deren Codierungsformat, die sich alle im BLOB-Container <container_name> im Azure Storage-Konto <account_name>befinden, über 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
);

Laden Sie Daten in die Tabelle. Führen Sie entweder INSERT-Anweisungen aus, um sie mit mehreren synthetischen Zeilen zu füllen, oder verwenden Sie die Importdaten mithilfe eines COPY FROM-Anweisungsbeispiels , um sie mit dem Inhalt des Beispieldatensatzes aufzufüllen.

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 blob_get zu wissen, wie Sie die Daten analysieren, können Sie einen Wert im Formular NULL::table_nameübergeben, 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 wir am Anfang erstellt haben.

<blob_name> sollte auf den vollständigen Pfad des Blobs festgelegt werden, dessen Inhalt Sie lesen möchten.

In diesem Fall wird der Decoder, der zum Analysieren des Blobs verwendet werden muss, 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 mithilfe der AS Klausel nach der blob_get-Funktion definieren.

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 die Möglichkeit veranschaulicht, den aus dem Blob importierten Inhalt zu filtern und zu ändern, bevor er in eine SQL-Tabelle geladen wird.

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 veranschaulicht, wie Sie benutzerdefinierte Trennzeichen und Escapezeichen verwenden können, indem Sie das Ergebnis options_copy an das options Argument übergeben.

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 die Decoderoption nicht vorhanden ist, wird sie von der Erweiterung der Datei abgeleitet. Wenn der Dateiname jedoch keine Erweiterung hat oder diese Dateinamenerweiterung nicht dem dem Decoder zugeordneten entspricht, der verwendet werden muss, 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 veranschaulicht, wie Sie Aggregationsvorgänge über Informationen ausführen können, 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 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 ist 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 veranschaulicht, wie Sie herausfinden können, auf welche Azure-Speicherkonten die azure_storage Erweiterung in dieser Datenbank verweisen kann, zusammen mit dem Authentifizierungstyp, der für den Zugriff auf jedes Speicherkonto verwendet wird, und welchen Benutzern oder Rollen über die Funktion azure_storage.account_user_add berechtigungen erteilt werden, um über die von der Erweiterung bereitgestellte Funktionalität auf dieses Azure-Speicherkonto zuzugreifen.

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 veranschaulicht, wie Der Zugriff von einem Benutzer oder einer Rolle mit dem Namen <regular_user>widerrufen wird, sodass ein solcher PostgreSQL-Benutzer die azure_storage Erweiterung nicht für den Zugriff auf die blobs verwenden kann, die in Containern gespeichert sind, die vom bezeichneten Azure-Speicherkonto gehostet werden.