Quickstartvoorbeelden voor de Azure Storage-extensie in Azure Database for PostgreSQL

Hieronder vindt u een lijst met voorbeelden voor meer informatie over het gebruik van de Azure Storage-extensie.

Een Azure Storage-account maken en vullen met gegevens

Een Azure Storage-account maken. Als u nog geen Azure Storage-account wilt maken, past u de waarden van <resource_group>, <location>en <account_name>en <container_name>voert u de volgende Azure CLI-opdracht uit:

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

Maak een blobcontainer. Voer de volgende Azure CLI uit om de blobcontainer te maken:

az storage container create --account-name $storage_account --name $blob_container -o tsv

Haal een van de twee toegangssleutels op die zijn toegewezen aan het opslagaccount. Zorg ervoor dat u de waarde van uw access_key kopieert omdat u deze als argument moet doorgeven aan azure_storage.account_add in een volgende stap. Voer de volgende Azure CLI-opdracht uit om de eerste van de twee toegangssleutels op te halen:
```
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
```

Download het bestand met de gegevensset die tijdens de voorbeelden wordt gebruikt en upload het naar uw blobcontainer. Voer de volgende Azure CLI-opdracht uit om het bestand te downloaden met de gegevensset:

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

Opmerking

U kunt containers of de blobs die erin zijn opgeslagen voor een specifiek opslagaccount weergeven, maar alleen als uw PostgreSQL-gebruiker of -rol is gemachtigd voor de verwijzing naar dat opslagaccount met behulp van azure_storage.account_user_add. Leden van de azure_storage_admin rol krijgen deze bevoegdheid toegewezen voor alle Azure Storage-accounts die zijn toegevoegd met behulp van azure_storage.account_add. Standaard worden alleen leden van azure_pg_admin de azure_storage_admin rol verleend.

Een tabel maken waarin gegevens worden geladen

Laten we de tabel maken waarin we de inhoud importeren van de bestanden die we hebben geüpload naar het opslagaccount. Hiervoor maakt u verbinding met uw exemplaar van Azure Database for PostgreSQL flexibele server met postgreSQL voor Visual Studio Code (preview), psql, PgAdmin of de client van uw voorkeur en voert u de volgende instructie uit:

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

De extensie voorbereiden voor gebruik

Voordat u doorgaat, moet u het volgende doen:

Toegangssleutel van opslagaccount toevoegen

In dit voorbeeld ziet u hoe u een verwijzing naar een opslagaccount toevoegt, samen met de toegangssleutel van dat opslagaccount dat nodig is voor toegang tot de inhoud ervan via de functionaliteit van de azure_storage extensie in uw exemplaar van flexibele Azure Database for PostgreSQL-server.

<account_name> moet worden ingesteld op de naam van uw opslagaccount. Als u de vorige scripts hebt gebruikt, moet deze waarde overeenkomen met de waarde die u hebt ingesteld op de storage_account omgevingsvariabele in deze scripts.

Op dezelfde manier <access_key> moet worden ingesteld op de waarde die u hebt opgehaald uit uw opslagaccount.

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

Aanbeveling

Als u de naam van het opslagaccount en een van de bijbehorende toegangssleutels uit Azure Portal wilt ophalen, zoekt u naar uw opslagaccount, selecteert u toegangssleutels in het resourcemenu, kopieert u de naam van het opslagaccount en kopieert u de sleutel uit de sectie Sleutel1 (u moet eerst Weergeven naast de sleutel selecteren).

Toegang verlenen tot een gebruiker of rol in de Naslaginformatie over Azure Blob Storage

In dit voorbeeld ziet u hoe u toegang verleent tot een gebruiker of rol met de naam <regular_user>, zodat een dergelijke PostgreSQL-gebruiker de azure_storage extensie kan gebruiken voor toegang tot de blobs die zijn opgeslagen in containers die worden gehost door het genoemde Azure-opslagaccount.

<regular_user> moet worden ingesteld op de naam van een bestaande gebruiker of rol.

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

Alle blobs in een container weergeven

In dit voorbeeld ziet u hoe u alle bestaande blobs in de container <container_name> van het opslagaccount <account_name>weer kunt geven.

<container_name> moet worden ingesteld op de naam van uw blobcontainer. Als u de vorige scripts hebt gebruikt, moet deze waarde overeenkomen met de waarde die u hebt ingesteld op de blob_container omgevingsvariabele in deze scripts.

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

Blobs weergeven met een specifiek naamvoorvoegsel

In dit voorbeeld ziet u hoe u alle bestaande blobs in de container <container_name> van het opslagaccount <account_name>weer kunt geven waarvan de blobnaam begint met <blob_name_prefix>.

<blob_name_prefix> moet worden ingesteld op het voorvoegsel dat de blobs moeten bevatten in hun namen. Als u alle blobs wilt retourneren, kunt u deze parameter instellen op een lege tekenreeks of zelfs geen waarde voor deze parameter opgeven. In dat geval wordt de waarde standaard ingesteld op een lege tekenreeks.

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

U kunt ook de volgende syntaxis gebruiken:

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

Gegevens importeren met een COPY FROM-instructie

In het volgende voorbeeld ziet u het importeren van gegevens uit een blob met de naam storage_extension_sample.parquet die zich in de blobcontainer <container_name> in het Azure Storage-account <account_name>bevindt, via de COPY opdracht:

Maak een tabel die overeenkomt met het schema van het bronbestand:

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

Gebruik een COPY instructie om gegevens naar de doeltabel te kopiëren. De indeling wordt afgeleid als Parquet uit de extensie van het bestand.

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

Gebruik een COPY instructie om gegevens naar de doeltabel te kopiëren. Omdat de coderingsindeling niet kan worden afgeleid van de bestandsextensie, wordt deze expliciet opgegeven via de FORMAT optie.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
Gebruik een COPY instructie om gegevens naar de doeltabel te kopiëren. De coderingsindeling kan worden afgeleid van de bestandsextensie. De aanwezigheid van kolomkoppen in de eerste rij moet echter expliciet worden geconfigureerd via HEADERS de optie.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Voer de volgende SELECT instructie uit om te bevestigen dat de gegevens in de tabel worden geladen.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Gegevens exporteren met een COPY TO-instructie

In de volgende voorbeelden ziet u het exporteren van gegevens uit een tabel met de naam sample_data, naar meerdere blobs met verschillende namen en kenmerken, zoals de coderingsindeling, die allemaal zich in de blobcontainer <container_name> in het Azure Storage-account <account_name>bevinden, via de COPY opdracht:

Maak een tabel die overeenkomt met het schema van het bronbestand:

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

Gegevens in de tabel laden. Voer INSERT-instructies uit om deze te vullen met verschillende synthetische rijen of gebruik de importgegevens met behulp van een COPY FROM-instructievoorbeeld om deze te vullen met de inhoud van de voorbeeldgegevensset.

Gebruik een COPY instructie om gegevens uit de doeltabel te kopiëren. Geef op dat de coderingsindeling parquet moet zijn.

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

Gebruik een COPY instructie om gegevens uit de doeltabel te kopiëren. Geef op dat de coderingsindeling CSV moet zijn en dat de eerste rij van het resulterende bestand kolomkoppen bevat.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Voer de volgende SELECT instructie uit om te bevestigen dat de blob bestaat in het opslagaccount.

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

Inhoud lezen uit een blob

De blob_get functie haalt de inhoud van één specifieke blob op in de container <container_name> van de opslag waarnaar <account_name> wordt verwezen. Als u wilt blob_get weten hoe u de gegevens kunt parseren, kunt u een waarde doorgeven in het formulier NULL::table_name, waarbij table_name wordt verwezen naar een tabel waarvan het schema overeenkomt met die van de blob die wordt gelezen. In het voorbeeld verwijst deze naar de sample_data tabel die we aan het begin hebben gemaakt.

<blob_name> moet worden ingesteld op het volledige pad van de blob waarvan u de inhoud wilt lezen.

In dit geval wordt de decoder die moet worden gebruikt om de blob te parseren afgeleid van de .parquet bestandsextensie.

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

U kunt ook expliciet het schema van het resultaat definiëren met behulp van de AS component na de blob_get functie.

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;

Inhoud lezen, filteren en wijzigen die wordt gelezen uit een blob

In dit voorbeeld ziet u de mogelijkheid om de inhoud die is geïmporteerd uit de blob te filteren en te wijzigen voordat u deze in een SQL-tabel laadt.

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;

Inhoud van bestand lezen met aangepaste opties (kopteksten, kolomscheidingstekens, escapetekens)

In dit voorbeeld ziet u hoe u aangepaste scheidingstekens en escapetekens kunt gebruiken door het resultaat van options_copy door te geven aan het options argument.

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

De decoderoptie gebruiken

In dit voorbeeld ziet u het gebruik van de decoder optie. Als de decoderoptie niet aanwezig is, wordt deze afgeleid van de extensie van het bestand. Maar als de bestandsnaam geen extensie heeft of wanneer die bestandsnaamextensie niet overeenkomt met de extensie die is gekoppeld aan de decoder die moet worden gebruikt om de inhoud van het bestand correct te parseren, kunt u het decoderargument expliciet doorgeven.

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

Berekeningsaggregaties over de inhoud van een blob

In dit voorbeeld ziet u hoe u aggregatiebewerkingen kunt uitvoeren op gegevens die zijn opgeslagen in een blobcontainer, zonder dat u de inhoud van de blob hoeft te importeren in PostgreSQL-tabellen.

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;

Inhoud naar een blob schrijven

De blob_put functie bevat de inhoud van één specifieke blob (sample_data_copy.parquetin dit geval) en uploadt deze naar de container van de <container_name> opslag waarnaar wordt verwezen<account_name>. In dit voorbeeld wordt gebruikgemaakt blob_get van het maken van een set van vijf rijen, die vervolgens worden doorgegeven aan de blob_put statistische functie die ze uploadt als een blob met de naam sample_data_copy.parquet.

De coderingsindeling wordt afgeleid als parquet, op basis van de bestandsextensie .parquet.

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;

De coderingsindeling wordt afgeleid als CSV, op basis van de bestandsextensie .csv.

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;

De coderingsindeling kan niet worden afgeleid omdat het bestand geen bestandsextensie heeft, dus het is expliciet geconfigureerd als parquet. Daarnaast is het compressie-algoritme ingesteld op 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;

Alle verwijzingen naar Azure-opslagaccounts weergeven

In dit voorbeeld ziet u hoe u kunt achterhalen welke Azure-opslagaccounts de azure_storage extensie kan raadplegen in deze database, samen met het type verificatie dat wordt gebruikt voor toegang tot elk opslagaccount en welke gebruikers of rollen machtigingen krijgen, via de functie azure_storage.account_user_add , voor toegang tot dat Azure-opslagaccount via de functionaliteit van de extensie.

SELECT * FROM azure_storage.account_list();

Toegang intrekken van een gebruiker of rol in de Naslaginformatie voor Azure Blob Storage

In dit voorbeeld ziet u hoe u de toegang kunt intrekken van een gebruiker of rol met de naam <regular_user>, zodat een dergelijke PostgreSQL-gebruiker de azure_storage extensie niet kan gebruiken voor toegang tot de blobs die zijn opgeslagen in containers die worden gehost door het genoemde Azure-opslagaccount.