Snabbstartsexempel för Azure Storage-tillägget i Azure Database for PostgreSQL

Här följer en lista med exempel som hjälper dig att lära dig hur du använder Azure Storage-tillägget.

Skapa ett Azure Storage-konto och fyll i det med data

skapa ett Azure Storage-konto Om du inte redan har ett Azure Storage-konto anpassar du värdena <resource_group>för , <location>, <account_name>och och <container_name>kör följande Azure CLI-kommando:

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

Skapa en blobcontainer. Kör följande Azure CLI för att skapa blobcontainern:

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

Hämta en av de två åtkomstnycklar som tilldelats lagringskontot. Kontrollera att du kopierar värdet för din access_key eftersom du behöver skicka det som ett argument till azure_storage.account_add i ett efterföljande steg. Om du vill hämta den första av de två åtkomstnycklarna kör du följande Azure CLI-kommando:
```
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
```

Ladda ned filen med datauppsättningen som används under exemplen och ladda upp den till din blobcontainer. Om du vill ladda ned filen med datauppsättningen kör du följande Azure CLI-kommando:

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

Anmärkning

Du kan visa containrar eller blobar som lagras i dem för ett visst lagringskonto, men bara om din PostgreSQL-användare eller roll beviljas behörighet för referensen till lagringskontot med hjälp av azure_storage.account_user_add. Medlemmar i rollen beviljas den här behörigheten azure_storage_admin för alla Azure Storage-konton som har lagts till med hjälp av azure_storage.account_add. Som standard beviljas endast medlemmar azure_pg_admin i azure_storage_admin rollen.

Skapa en tabell där data läses in

Nu ska vi skapa tabellen där vi importerar innehållet i de filer som vi laddade upp till lagringskontot. Det gör du genom att ansluta till din instans av Azure Database for PostgreSQL – flexibel server med PostgreSQL för Visual Studio Code (förhandsversion), psql, PgAdmin eller klienten som du föredrar, och kör följande instruktion:

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

Förbereda tillägget för användning

Innan du fortsätter kontrollerar du att du:

Lägga till åtkomstnyckel för lagringskonto

Det här exemplet illustrerar hur du lägger till en referens till ett lagringskonto, tillsammans med åtkomstnyckeln för det lagringskonto som krävs för att få åtkomst till dess innehåll via de funktioner som tillhandahålls av azure_storage tillägget i din instans av Azure Database for PostgreSQL – flexibel server.

<account_name> måste anges till namnet på ditt lagringskonto. Om du använde föregående skript bör det här värdet matcha det värde som du har angett till storage_account miljövariabeln i dessa skript.

<access_key> På samma sätt måste anges till det värde som du hämtade från ditt lagringskonto.

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

Tips/Råd

Om du vill hämta lagringskontots namn och en av dess åtkomstnycklar från Azure-portalen söker du efter ditt lagringskonto. På resursmenyn väljer du Åtkomstnycklar, kopierar lagringskontots namn och kopierar avsnittet Nyckel från key1 (du måste välja Visa bredvid nyckeln först).

Bevilja åtkomst till en användare eller roll i Azure Blob Storage-referensen

Det här exemplet visar hur du beviljar åtkomst till en användare eller roll med namnet <regular_user>, så att en sådan PostgreSQL-användare kan använda azure_storage tillägget för att komma åt blobarna som lagras i containrar som hanteras av det refererade Azure Storage-kontot.

<regular_user> måste anges till namnet på en befintlig användare eller roll.

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

Visa en lista över alla blobar i en container

Det här exemplet visar hur du listar alla befintliga blobar i containern <container_name> för lagringskontot <account_name>.

<container_name> måste anges till namnet på blobcontainern. Om du använde föregående skript ska det här värdet matcha det värde som du har angett till blob_container miljövariabeln i dessa skript.

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

Lista blobar med ett specifikt namnprefix

Det här exemplet visar hur du listar alla befintliga blobar i containern <container_name> för lagringskontot <account_name>, vars blobnamn börjar med <blob_name_prefix>.

<blob_name_prefix> ska anges till det prefix som du vill att blobarna ska innehålla i deras namn. Om du vill returnera alla blobar kan du ange den här parametern till en tom sträng eller inte ens ange ett värde för den här parametern, i vilket fall värdet som standard är en tom sträng.

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

Du kan också använda följande syntax:

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

Importera data med en COPY FROM-instruktion

I följande exempel visas importen av data från en blob med namnet storage_extension_sample.parquet som finns i blobcontainern <container_name> i Azure Storage-kontot <account_name>via COPY kommandot :

Skapa en tabell som matchar källfilens schema:

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

Använd en COPY instruktion för att kopiera data till måltabellen. Formatet härleds som Parquet från filnamnstillägget.

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

Använd en COPY instruktion för att kopiera data till måltabellen. Eftersom kodningsformatet inte kan härledas från filnamnstillägget anges det uttryckligen via FORMAT alternativet .
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/parquet_without_extension'
WITH (FORMAT 'parquet');
```
Använd en COPY instruktion för att kopiera data till måltabellen. Kodningsformatet kan härledas från filnamnstillägget. Förekomsten av kolumnrubriker på den första raden måste dock konfigureras explicit via HEADERS alternativet.
```
TRUNCATE TABLE sample_data;
COPY sample_data
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample.csv'
WITH (HEADERS);
```
Kör följande SELECT instruktion för att bekräfta att data läses in i tabellen.
```
SELECT *
FROM sample_data
LIMIT 100;
```

Exportera data med en COPY TO-instruktion

I följande exempel visas exporten av data från en tabell med namnet sample_data, till flera blobar med olika namn och egenskaper som deras kodningsformat, som alla finns i blobcontainern <container_name> i Azure Storage-kontot <account_name>, via COPY kommandot :

Skapa en tabell som matchar källfilens schema:

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

Läs in data i tabellen. Kör antingen INSERT-instruktioner för att fylla den med flera syntetiska rader eller använd importdata med hjälp av ett COPY FROM-instruktionsexempel för att fylla i dem med innehållet i exempeldatauppsättningen.

Använd en COPY instruktion för att kopiera data från måltabellen. Ange att kodningsformatet måste vara parquet.

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

Använd en COPY instruktion för att kopiera data från måltabellen. Ange att kodningsformatet måste vara CSV och att den första raden i den resulterande filen innehåller kolumnrubriker.
```
COPY sample_data
TO 'https://<account_name>.blob.core.windows.net/<container_name>/storage_extension_sample_exported.csv'
WITH (FORMAT 'csv', HEADERS);
```

Kör följande SELECT instruktion för att bekräfta att bloben finns i lagringskontot.

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

Läsa innehåll från en blob

Funktionen blob_get hämtar innehållet i en specifik blob i den refererade containern <container_name> för lagringen <account_name> . För att veta blob_get hur du parsar data kan du skicka ett värde i formuläret NULL::table_name, där table_name refererar till en tabell vars schema matchar den blob som läse. I exemplet refererar det till tabellen sample_data som vi skapade i början.

<blob_name> ska anges till den fullständiga sökvägen för den blob vars innehåll du vill läsa.

I det här fallet härleds den avkodare som måste användas för att parsa blobben från filnamnstillägget .parquet .

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

Du kan också uttryckligen definiera schemat för resultatet med hjälp AS av -satsen efter funktionen 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;

Läsa, filtrera och ändra innehåll som lästs från en blob

Det här exemplet illustrerar möjligheten att filtrera och ändra innehållet som importerats från blobben innan det läses in i en SQL-tabell.

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;

Läsa innehåll från en fil med anpassade alternativ (rubriker, kolumnavgränsare, escape-tecken)

Det här exemplet illustrerar hur du kan använda anpassade avgränsare och escape-tecken genom att skicka resultatet av options_copy till options argumentet.

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

Använd avkodningsalternativet

Det här exemplet illustrerar användningen av decoder alternativet. När avkodaralternativet inte finns härleds det från filnamnstillägget. Men om filnamnet inte har något tillägg, eller om filnamnstillägget inte motsvarar det som är associerat med avkodaren som måste användas för att korrekt parsa innehållet i filen, kan du uttryckligen skicka avkodarargumentet.

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

Beräkningsaggregeringar över innehållet i en blob

Det här exemplet illustrerar hur du kan utföra aggregeringsåtgärder över information som lagras i en blobcontainer, utan att behöva importera innehållet i bloben till PostgreSQL-tabeller.

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;

Skriva innehåll till en blob

Funktionen blob_put består av innehållet i en specifik blob (sample_data_copy.parquet i det här fallet) och laddar upp den till den refererade containern <container_name> för lagringen <account_name> . I det här exemplet används blob_get för att skapa en uppsättning med fem rader, som sedan skickas till den blob_put mängdfunktion som överför dem som en blob med namnet sample_data_copy.parquet.

Kodningsformatet härleds som parquet, baserat på filnamnstillägget .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;

Kodningsformatet härleds som CSV, baserat på filnamnstillägget .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;

Det går inte att härleda kodningsformatet eftersom filen inte har något filnamnstillägg, så det är uttryckligen konfigurerat som parquet. Komprimeringsalgoritmen är också inställd på 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;

Visa en lista över alla referenser till Azure Storage-konton

Det här exemplet visar hur du tar reda på vilka Azure-lagringskonton azure_storage tillägget kan referera till i den här databasen, tillsammans med den typ av autentisering som används för att komma åt varje lagringskonto och vilka användare eller roller som beviljas behörighet, via funktionen azure_storage.account_user_add , för att få åtkomst till azure-lagringskontot via de funktioner som tillhandahålls av tillägget.

SELECT * FROM azure_storage.account_list();

Återkalla åtkomst från en användare eller roll i Azure Blob Storage-referensen

Det här exemplet visar hur du återkallar åtkomst från en användare eller roll med namnet <regular_user>, så att en sådan PostgreSQL-användare inte kan använda azure_storage tillägget för att komma åt blobarna som lagras i containrar som hanteras av det refererade Azure-lagringskontot.