Gegevens importeren en exporteren met behulp van azure_storage-extensie in Azure Database for PostgreSQL - Flexible Server

Artikel
11/19/2024

VAN TOEPASSING OP: Azure Database for PostgreSQL - Flexibele server

Met de azure_storage-extensie kunt u gegevens in meerdere bestandsindelingen importeren of exporteren, rechtstreeks tussen Azure Storage-accounts en een exemplaar van Azure Database for PostgreSQL Flexible Server.

Voorbeelden van het exporteren en importeren van gegevens met deze extensie vindt u in de sectie Voorbeelden van dit artikel.

Als u de azure_storage extensie wilt gebruiken op uw flexibele Azure Database for PostgreSQL-serverexemplaren, moet u de extensie toestaan, de bibliotheek laden en de extensie maken.

Overzicht van de procedure

Identificeer de Azure Storage-accounts waarmee gebruikers van de azure_storage extensie moeten communiceren.
Bepaal welk type autorisatie u wilt gebruiken voor de aanvragen die zijn gedaan voor de blobservice van elk van deze Azure Storage-accounts. azure_storage extensie ondersteunt autorisatie met gedeelde sleutel en autorisatie met Microsoft Entra-id. Van deze twee typen autorisatie biedt Microsoft Entra ID een superieure beveiliging en gebruiksgemak ten opzichte van gedeelde sleutels en wordt door Microsoft aanbevolen. Volg de instructies in de bijbehorende secties om te voldoen aan de vereisten die in elk geval nodig zijn:
- Autorisatie met Microsoft Entra-id of
- Autorisatie met gedeelde sleutel.
Opnemen azure_storage in shared_preload_libraries:

Omdat de shared_preload_libraries server statisch is, moet de server opnieuw worden opgestart om een wijziging van kracht te laten worden:

az postgres flexible-server parameter set --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name shared_preload_libraries --source user-override --value azure_storage,$(az postgres flexible-server parameter show --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name shared_preload_libraries --query value --output tsv)

Omdat de shared_preload_libraries server statisch is, moet de server opnieuw worden opgestart om een wijziging van kracht te laten worden:

az postgres flexible-server restart --resource-group <flexible_server_resource_group> --name <flexible_server_name>

Opnemen azure_storage in azure.extensions:

az postgres flexible-server parameter set --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name azure.extensions --source user-override --value azure_storage,$(az postgres flexible-server parameter show --resource-group <flexible_server_resource_group> --server-name <flexible_server_name> --name azure.extensions --query value --output tsv)

Gebruik de client van uw voorkeur (bijvoorbeeld psql, pgAdmin, enzovoort) om verbinding te maken met een database in uw exemplaar van Azure Database for PostgreSQL Flexible Server. Als u alle SQL-objecten (tabellen, typen, functies, weergaven, enzovoort) wilt maken waarmee u de azure_storage extensie kunt gebruiken om te communiceren met exemplaren van Azure Storage-accounts, voert u de volgende instructie uit:
```
CREATE EXTENSION azure_storage;
```
Voeg met behulp van de azure_storage.account_* functies verwijzingen toe naar Azure Storage-accounts waarmee u PostgreSQL-gebruikers of -rollen toegang wilt geven met de azure_storage extensie. Deze verwijzingen omvatten de naam van het Azure Storage-account waarnaar wordt verwezen en het verificatietype dat moet worden gebruikt bij interactie met het Azure Storage-account. Afhankelijk van het geselecteerde verificatietype moet u mogelijk ook enkele andere parameters opgeven, zoals de toegangssleutel van het Azure Storage-account of het SAS-token.

Belangrijk

Voor verificatietypen waarvoor u een toegangssleutel voor een Azure Storage-account moet opgeven, ziet u dat uw Azure Storage-toegangssleutels vergelijkbaar zijn met een hoofdwachtwoord voor uw opslagaccount. Wees altijd voorzichtig om ze te beschermen. Gebruik Azure Key Vault om uw sleutels veilig te beheren en te roteren. azure_storage extensie slaat deze sleutels op in een tabel azure_storage.accounts die kan worden gelezen door leden van de pg_read_all_data rol.

Gebruikers die de azure_storage_admin rol hebben verleend, kunnen communiceren met de azure_storage.accounts tabel met behulp van de volgende functies:

azure_storage.account_add
azure_storage.account_list
azure_storage.account_remove
azure_storage.account_user_add
azure_storage.account_user_remove

De azure_storage_admin rol wordt standaard verleend aan de azure_pg_admin rol.

Autorisatie gebruiken met Microsoft Entra-id

Schakel door het systeem toegewezen beheerde identiteit in op uw exemplaar van Azure Database for PostgreSQL Flexible Server.

az rest --method patch --url https://management.azure.com/subscriptions/<subscriptionId>/resourceGroups/<flexible_server_resource_group>/providers/Microsoft.DBforPostgreSQL/flexibleServers/<flexible_server_name>?api-version=2024-08-01 --body '{"identity":{"type":"SystemAssigned"}}'

Start het exemplaar van Azure Database for PostgreSQL Flexible Server opnieuw op nadat er een door het systeem toegewezen beheerde identiteit is ingeschakeld.
Wijs op rollen gebaseerd toegangsbeheer (RBAC) machtigingen toe voor toegang tot blobgegevens in het Azure Storage-account aan de door het systeem toegewezen beheerde identiteit van uw exemplaar van Azure Database for PostgreSQL Flexible Server.

Autorisatie gebruiken met gedeelde sleutel

Voor uw Azure Storage-account moet toegang tot de sleutel van het opslagaccount zijn ingeschakeld (de eigenschap AllowSharedKeyAccess kan dus niet zijn ingesteld op false).

az storage account update --resource-group <storage_account_resource_group> --name <account_name> --allow-shared-key-access true

Als u deze wilt doorgeven aan de functie azure_storage.account_add , haalt u een van de twee toegangssleutels van het Azure Storage-account op.

az storage account keys list --resource-group <storage_account_resource_group> --account-name <account_name> --query [0].value -o tsv

Functies

azure_storage.account_add

Functie waarmee u een opslagaccount en de bijbehorende toegangssleutel kunt toevoegen aan de lijst met opslagaccounts waartoe de azure_storage extensie toegang heeft.

Als een eerdere aanroep van deze functie al de verwijzing naar dit opslagaccount heeft toegevoegd, wordt er geen nieuwe vermelding toegevoegd, maar wordt in plaats daarvan de toegangssleutel van de bestaande vermelding bijgewerkt.

Notitie

Met deze functie wordt niet gevalideerd of de naam van het bedoelde account bestaat of als deze toegankelijk is met de opgegeven toegangssleutel. Er wordt echter gevalideerd dat de naam van het opslagaccount geldig is, volgens de naamgevingsvalidatieregels die zijn opgelegd aan Azure-opslagaccounts.

azure_storage.account_add(account_name_p text, account_key_p text);

Er is een overbelaste versie van deze functie, die een account_config parameter accepteert die de naam van het Azure Storage-account waarnaar wordt verwezen, en alle vereiste instellingen, zoals verificatietype, accounttype of opslagreferenties.

azure_storage.account_add(account_config jsonb);

Machtigingen

Moet lid zijn van azure_storage_admin.

Argumenten

account_name_p

text de naam van het Azure Blob Storage-account dat al uw objecten bevat: blobs, bestanden, wachtrijen en tabellen. Het opslagaccount biedt een unieke naamruimte die overal ter wereld toegankelijk is via HTTPS.

account_key_p

text de waarde van een van de toegangssleutels voor het opslagaccount. Uw toegangssleutels voor Azure Blob Storage zijn vergelijkbaar met een hoofdwachtwoord voor uw opslagaccount. Wees altijd voorzichtig met het beveiligen van uw toegangssleutels. Gebruik Azure Key Vault om uw sleutels veilig te beheren en te roteren. De accountsleutel wordt opgeslagen in een tabel die alleen toegankelijk is voor de supergebruiker. Gebruikers die de azure_storage_admin rol hebben verleend, kunnen communiceren met deze tabel via functies. Als u wilt zien welke opslagaccounts worden toegevoegd, gebruikt u de functie azure_storage.account_list.

account_config

jsonb de naam van het Azure Storage-account en alle vereiste instellingen, zoals verificatietype, accounttype of opslagreferenties. U wordt aangeraden de hulpprogrammafuncties azure_storage.account_options_managed_identity, azure_storage.account_options_credentials of azure_storage.account_options te gebruiken om een van de geldige waarden te maken die als dit argument moeten worden doorgegeven.

Retourtype

VOID

azure_storage.account_options_managed_identity

Functie die fungeert als een hulpprogrammafunctie, die kan worden aangeroepen als een parameter binnen azure_storage.account_add, en is handig om een geldige waarde voor het argument te produceren wanneer u een door het account_config systeem toegewezen beheerde identiteit gebruikt om te communiceren met het Azure Storage-account.

azure_storage.account_options_managed_identity(name text, type azure_storage.storage_type);

Machtigingen

Elke gebruiker of rol kan deze functie aanroepen.

Argumenten

naam

type

azure_storage.storage_type de waarde van een van de ondersteunde typen opslag. Alleen ondersteunde waarde is blob.

Retourtype

jsonb

azure_storage.account_options_credentials

Functie die fungeert als een hulpprogrammafunctie, die kan worden aangeroepen als een parameter binnen azure_storage.account_add, en is handig om een geldige waarde voor het account_config argument te produceren wanneer u een Azure Storage-toegangssleutel gebruikt om te communiceren met het Azure Storage-account.

azure_storage.account_options_credentials(name text, credentials text, type azure_storage.storage_type);

Machtigingen

Elke gebruiker of rol kan deze functie aanroepen.

Argumenten

naam

aanmeldingsgegevens

type

azure_storage.storage_type de waarde van een van de ondersteunde typen opslag. Alleen ondersteunde waarde is blob.

Retourtype

jsonb

azure_storage.account_options

Functie die fungeert als een hulpprogrammafunctie, die kan worden aangeroepen als een parameter binnen azure_storage.account_add, en is handig om een geldige waarde voor het account_config argument te produceren wanneer u een Azure Storage-toegangssleutel of een door het systeem toegewezen beheerde identiteit gebruikt om te communiceren met het Azure Storage-account.

azure_storage.account_options(name text, auth_type azure_storage.auth_type, storage_type azure_storage.storage_type, credentials text DEFAULT NULL);

Machtigingen

Elke gebruiker of rol kan deze functie aanroepen.

Argumenten

naam

auth_type

azure_storage.auth_type de waarde van een van de ondersteunde typen opslag. Alleen ondersteunde waarden zijn access-key, en managed-identity.

storage_type

azure_storage.storage_type de waarde van een van de ondersteunde typen opslag. Alleen ondersteunde waarde is blob.

aanmeldingsgegevens

Retourtype

jsonb

azure_storage.account_remove

Functie waarmee een opslagaccount en de bijbehorende toegangssleutel kunnen worden verwijderd uit de lijst met opslagaccounts waartoe de azure_storage extensie toegang heeft.

azure_storage.account_remove(account_name_p text);

Machtigingen

Moet lid zijn van azure_storage_admin.

Argumenten

account_name_p

Retourtype

VOID

azure_storage.account_user_add

Functie waarmee een PostgreSQL-gebruiker of -rol toegang kan worden verleend tot een opslagaccount via de functies van de azure_storage extensie.

Notitie

De uitvoering van deze functie slaagt alleen als het opslagaccount, waarvan de naam wordt doorgegeven als het eerste argument, al is gemaakt met behulp van azure_storage.account_add, en als de gebruiker of rol, waarvan de naam wordt doorgegeven als het tweede argument, al bestaat.

azure_storage.account_add(account_name_p text, user_p regrole);

Machtigingen

Moet lid zijn van azure_storage_admin.

Argumenten

account_name_p

user_p

regrole de naam van een PostgreSQL-gebruiker of -rol die beschikbaar is op de server.

Retourtype

VOID

azure_storage.account_user_remove

Functie die het intrekken van een PostgreSQL-gebruiker of -roltoegang tot een opslagaccount toestaat via de functies van de azure_storage extensie.

Notitie

De uitvoering van deze functie slaagt alleen als het opslagaccount waarvan de naam wordt doorgegeven als het eerste argument al is gemaakt met behulp van azure_storage.account_add, en als de gebruiker of rol waarvan de naam wordt doorgegeven als het tweede argument nog steeds bestaat. Wanneer een gebruiker of rol van de server wordt verwijderd door uit te DROP USER | ROLEvoeren, worden de machtigingen die zijn verleend op een verwijzing naar Azure Storage-accounts ook automatisch verwijderd.

azure_storage.account_user_remove(account_name_p text, user_p regrole);

Machtigingen

Moet lid zijn van azure_storage_admin.

Argumenten

account_name_p

user_p

regrole de naam van een PostgreSQL-gebruiker of -rol die beschikbaar is op de server.

Retourtype

VOID

azure_storage.account_list

Functie met de namen van de opslagaccounts die zijn geconfigureerd via de functie azure_storage.account_add , samen met de PostgreSQL-gebruikers of -rollen die zijn gemachtigd om met dat opslagaccount te communiceren via de functies van de azure_storage extensie.

azure_storage.account_list();

Machtigingen

Moet lid zijn van azure_storage_admin.

Argumenten

Deze functie heeft geen argumenten.

Retourtype

TABLE(account_name text, auth_type azure_storage.auth_type, azure_storage_type azure_storage.storage_type, allowed_users regrole[]) een tabel met vier kolommen met de lijst met Toegevoegde Azure Storage-accounts, het type verificatie dat wordt gebruikt voor interactie met elk account, het type opslag en de lijst met PostgreSQL-gebruikers of -rollen die toegang tot het account krijgen.

azure_storage.blob_list

Functie met de namen en andere eigenschappen (grootte, lastModified, eTag, contentType, contentEncoding en contentHash) van blobs die zijn opgeslagen in de opgegeven container van het bedoelde opslagaccount.

azure_storage.blob_list(account_name text, container_name text, prefix text DEFAULT ''::text);

Machtigingen

Gebruiker of rol die deze functie aanroept, moet worden toegevoegd aan de lijst met toegestane functies voor de account_name verwijzing door azure_storage.account_user_add uit te voeren. Leden van de groep mogen automatisch verwijzen naar alle Azure Storage-accounts waarvan de verwijzingen zijn toegevoegd met behulp van azure_storage_admin azure_storage.account_add.

Argumenten

account_name

container_name

text de naam van een container. Een container kan een of meer blobs bevatten, net zoals een map een of meer bestanden kan bevatten in een bestandssysteem. Een opslagaccount kan een onbeperkt aantal containers bevatten en een container kan een onbeperkt aantal blobs bevatten. Een containernaam moet een geldige DNS-naam (Domain Name System) zijn, omdat deze deel uitmaakt van de unieke URI die wordt gebruikt om de container of de bijbehorende blobs te adresseren. Zorg ervoor dat u deze regels volgt bij het benoemen van een container.

De URI voor een container is vergelijkbaar met: https://myaccount.blob.core.windows.net/mycontainer

voorvoegsel

text indien opgegeven, retourneert de functie de blobs waarvan de namen beginnen met de waarde die in deze parameter is opgegeven. Standaard ingesteld op een lege tekenreeks.

Retourtype

TABLE(path text, bytes bigint, last_modified timestamp with time zone, etag text, content_type text, content_encoding text, content_hash text) een tabel met één record per blob geretourneerd, inclusief de volledige naam van de blob en enkele andere eigenschappen.

path

text de volledige naam van de blob.

bytes

bigint de grootte van de blob in bytes.

last_modified

timestamp with time zonede datum en tijd waarop de blob het laatst is gewijzigd. Elke bewerking die de blob wijzigt, inclusief een update van de metagegevens of eigenschappen van de blob, wijzigt de laatste wijzigingstijd van de blob.

etag

text de eigenschap ETag wordt gebruikt voor optimistische gelijktijdigheid tijdens updates. Het is geen tijdstempel omdat er een andere eigenschap is met de naam Timestamp waarin de laatste keer dat een record is bijgewerkt, wordt opgeslagen. Als u bijvoorbeeld een entiteit laadt en deze wilt bijwerken, moet de ETag overeenkomen met wat momenteel is opgeslagen. Het instellen van de juiste ETag is belangrijk omdat als u meerdere gebruikers hetzelfde item bewerkt, u niet wilt dat ze elkaars wijzigingen overschrijven.

content_type

text het inhoudstype dat is opgegeven voor de blob. Het standaardinhoudstype is application/octet-stream.

content_encoding

text de eigenschap Content-Encoding van een blob die u met Azure Storage kunt definiëren. Voor gecomprimeerde inhoud kunt u de eigenschap instellen op Gzip. Wanneer de browser toegang heeft tot de inhoud, wordt de inhoud automatisch gedecomprimeert.

content_hash

text de hash die wordt gebruikt om de integriteit van de blob tijdens het transport te controleren. Wanneer deze header is opgegeven, controleert de opslagservice de opgegeven hash met één hash die wordt berekend op basis van inhoud. Als de twee hashes niet overeenkomen, mislukt de bewerking met foutcode 400 (Ongeldige aanvraag).

azure_storage.blob_get

Functie waarmee gegevens kunnen worden geïmporteerd. Er wordt een bestand gedownload uit een blobcontainer in een Azure Storage-account. Vervolgens wordt de inhoud omgezet in rijen, die kunnen worden gebruikt en verwerkt met SQL-taalconstructies. Met deze functie wordt ondersteuning toegevoegd voor het filteren en bewerken van de gegevens die zijn opgehaald uit de blobcontainer voordat u deze importeert.

Notitie

Voordat u toegang probeert te krijgen tot de container voor het bedoelde opslagaccount, controleert deze functie of de namen van het opslagaccount en de container die als argumenten zijn doorgegeven, geldig zijn volgens de naamgevingsvalidatieregels die zijn opgelegd voor Azure-opslagaccounts. Als een van deze twee ongeldig is, wordt er een fout gegenereerd.

azure_storage.blob_get(account_name text, container_name text, path text, decoder text DEFAULT 'auto'::text, compression text DEFAULT 'auto'::text, options jsonb DEFAULT NULL::jsonb);

Er is een overbelaste versie van deze functie, die een rec parameter accepteert waarmee u de uitvoerindelingrecord gemakkelijk kunt definiëren.

azure_storage.blob_get(account_name text, container_name text, path text, rec anyelement, decoder text DEFAULT 'auto'::text, compression text DEFAULT 'auto'::text, options jsonb DEFAULT NULL::jsonb);

Machtigingen

Argumenten

account_name

container_name

De URI voor een container is vergelijkbaar met: https://myaccount.blob.core.windows.net/mycontainer

path

text de volledige naam van de blob.

Rec

anyelement de definitie van de recorduitvoerstructuur.

Decoder

text de specificatie van de blob-indeling. Kan worden ingesteld op een van de volgende waarden:

Notatie	Standaard	Beschrijving
`auto`	`true`	Hiermee wordt de waarde afgeleid op basis van de laatste reeks tekens die zijn toegewezen aan de naam van de blob. Als de blobnaam eindigt op `.csv` of `.csv.gz`, wordt ervan uitgegaan `csv`. Als het eindigt met `.tsv` of `.tsv.gz`, wordt ervan uitgegaan `tsv`. Als het eindigt met , , , , `.xml.gz`, of `.txt.gz.txt`, wordt ervan uitgegaan `text`. `.xml.json.gz.json`
`csv`		Door komma's gescheiden waardenindeling die wordt gebruikt door PostgreSQL COPY.
`tsv`		Door tabs gescheiden waarden, de standaardIndeling PostgreSQL COPY.
`binary`		Binaire PostgreSQL COPY-indeling.
`text` \| `xml` \| `json`		Een bestand met één tekstwaarde.

compressie

text de specificatie van het compressietype. Kan worden ingesteld op een van de volgende waarden:

Notatie	Standaard	Beschrijving
`auto`	`true`	Hiermee wordt de waarde afgeleid op basis van de laatste reeks tekens die zijn toegewezen aan de naam van de blob. Als de blobnaam eindigt, `.gz`wordt ervan uitgegaan `gzip`. Anders wordt ervan uitgegaan `none`.
`gzip`		Dwingt het gebruik van gzip-decoder om de blob te decomprimeren.
`none`		Krachten om de blob te behandelen als een blob die geen decompressie vereist.

De extensie biedt geen ondersteuning voor andere compressietypen.

Opties

jsonb de instellingen voor het afhandelen van aangepaste headers, aangepaste scheidingstekens, escapetekens, enzovoort. options beïnvloedt het gedrag van deze functie op een manier die vergelijkbaar is met de manier waarop de opties die u aan de COPY opdracht in PostgreSQL kunt doorgeven, van invloed zijn op het gedrag ervan.

Retourtype

SETOF record SETOF anyelement

azure_storage.blob_put

Functie waarmee u gegevens kunt exporteren door bestanden te uploaden naar een blobcontainer in een Azure Storage-account. De inhoud van de bestanden wordt geproduceerd uit rijen in PostgreSQL.

Notitie

azure_storage.blob_put(account_name text, container_name text, path text, tuple record)
RETURNS VOID;

Er is een overbelaste versie van de functie, die parameter bevat encoder waarmee u de encoder kunt opgeven die moet worden gebruikt wanneer deze niet kan worden afgeleid van de extensie van de path parameter, of wanneer u de parameter wilt overschrijven.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text)
RETURNS VOID;

Er is een overbelaste versie van de functie die ook een compression parameter bevat waarmee u de compressie kunt opgeven die moet worden gebruikt wanneer deze niet kan worden afgeleid van de extensie van de path parameter, of wanneer u de compressie wilt overschrijven.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text, compression text)
RETURNS VOID;

Er is een overbelaste versie van de functie die ook een options parameter bevat voor het verwerken van aangepaste headers, aangepaste scheidingstekens, escapetekens, enzovoort. options Werkt op dezelfde manier als de opties die kunnen worden doorgegeven aan de COPY opdracht in PostgreSQL.

azure_storage.blob_put(account_name text, container_name text, path text, tuple record, encoder text, compression text, options jsonb)
RETURNS VOID;

Machtigingen

Argumenten

account_name

container_name

De URI voor een container is vergelijkbaar met: https://myaccount.blob.core.windows.net/mycontainer

path

text de volledige naam van de blob.

tuple

record de definitie van de recorduitvoerstructuur.

encoder

text de specificatie van de blob-indeling. Kan worden ingesteld op een van de volgende waarden:

Notatie	Standaard	Beschrijving
`auto`	`true`	Hiermee wordt de waarde afgeleid op basis van de laatste reeks tekens die zijn toegewezen aan de naam van de blob. Als de blobnaam eindigt op `.csv` of `.csv.gz`, wordt ervan uitgegaan `csv`. Als het eindigt met `.tsv` of `.tsv.gz`, wordt ervan uitgegaan `tsv`. Als het eindigt met , , , , `.xml.gz`, of `.txt.gz.txt`, wordt ervan uitgegaan `text`. `.xml.json.gz.json`
`csv`		Door komma's gescheiden waardenindeling die wordt gebruikt door PostgreSQL COPY.
`tsv`		Door tabs gescheiden waarden, de standaardIndeling PostgreSQL COPY.
`binary`		Binaire PostgreSQL COPY-indeling.
`text` \| `xml` \| `json`		Een bestand met één tekstwaarde.

compressie

text de specificatie van het compressietype. Kan worden ingesteld op een van de volgende waarden:

Notatie	Standaard	Beschrijving
`auto`	`true`	Hiermee wordt de waarde afgeleid op basis van de laatste reeks tekens die zijn toegewezen aan de naam van de blob. Als de blobnaam eindigt, `.gz`wordt ervan uitgegaan `gzip`. Anders wordt ervan uitgegaan `none`.
`gzip`		Dwingt het gebruik van gzip-decoder om de blob te decomprimeren.
`none`		Krachten om de blob te behandelen als een blob die geen decompressie vereist.

De extensie biedt geen ondersteuning voor andere compressietypen.

Opties

Retourtype

VOID

azure_storage.options_csv_get

Functie die fungeert als een hulpprogrammafunctie, die kan worden aangeroepen als een parameter binnen blob_get, en is handig voor het decoderen van de inhoud van een CSV-bestand.

azure_storage.options_csv_get(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, header boolean DEFAULT NULL::boolean, quote text DEFAULT NULL::text, escape text DEFAULT NULL::text, force_not_null text[] DEFAULT NULL::text[], force_null text[] DEFAULT NULL::text[], content_encoding text DEFAULT NULL::text);

Machtigingen

Elke gebruiker of rol kan deze functie aanroepen.

Argumenten

scheidingsteken

text het teken dat kolommen scheidt binnen elke rij (regel) van het bestand. Het moet één byteteken zijn. Hoewel deze functie scheidingstekens van een willekeurig aantal tekens ondersteunt, meldt PostgreSQL een COPY delimiter must be a single one-byte character fout als u meer dan één byteteken probeert te gebruiken.

null_string

text de tekenreeks die een null-waarde vertegenwoordigt. De standaardwaarde is \N (backslash-N) in tekstindeling en een niet-aanhalingstekenloze lege tekenreeks in CSV-indeling. Mogelijk geeft u de voorkeur aan een lege tekenreeks, zelfs in tekstindeling voor gevallen waarin u null-waarden niet wilt onderscheiden van lege tekenreeksen.

boolean vlag die aangeeft of het bestand een koptekstregel bevat met de namen van elke kolom in het bestand. In de uitvoer bevat de eerste regel de kolomnamen uit de tabel.

citaat

text het aanhalingsteken dat moet worden gebruikt wanneer een gegevenswaarde wordt aanhalingstekens. De standaardwaarde is dubbele aanhalingstekens. Het moet één byteteken zijn. Hoewel deze functie scheidingstekens van een willekeurig aantal tekens ondersteunt, meldt PostgreSQL een COPY quote must be a single one-byte character fout als u meer dan één byteteken probeert te gebruiken.

escape

text het teken dat moet worden weergegeven vóór een gegevensteken dat overeenkomt met de prijsopgavewaarde. De standaardwaarde is hetzelfde als de prijsopgavewaarde (zodat het aanhalingsteken wordt verdubbeld als het in de gegevens wordt weergegeven). Het moet één byteteken zijn. Hoewel deze functie scheidingstekens van een willekeurig aantal tekens ondersteunt, meldt PostgreSQL een COPY escape must be a single one-byte character fout als u meer dan één byteteken probeert te gebruiken.

force_not_null

text[] komen niet overeen met de waarden van de opgegeven kolommen ten opzichte van de null-tekenreeks. In het standaardscenario waarin de null-tekenreeks leeg is, betekent dit dat lege waarden worden gelezen als tekenreeksen met de lengte nul in plaats van nullen, zelfs wanneer ze niet worden geciteerd.

force_null

text[] koppel de waarden van de opgegeven kolommen aan de null-tekenreeks, zelfs als deze wordt aanhalingstekens gegeven en als er een overeenkomst wordt gevonden, stelt u de waarde in op NULL. In het standaardscenario waarin de null-tekenreeks leeg is, wordt een lege tekenreeks tussen aanhalingstekens omgezet in NULL.

content_encoding

text naam van de codering waarmee het bestand is gecodeerd. Als de optie wordt weggelaten, wordt de huidige clientcodering gebruikt.

Retourtype

jsonb

azure_storage.options_copy

Functie die fungeert als een hulpprogrammafunctie, die kan worden aangeroepen als een parameter binnen blob_get. Het fungeert als helperfunctie voor options_csv_get, options_tsv en options_binary.

azure_storage.options_copy(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, header boolean DEFAULT NULL::boolean, quote text DEFAULT NULL::text, escape text DEFAULT NULL::text, force_quote text[] DEFAULT NULL::text[], force_not_null text[] DEFAULT NULL::text[], force_null text[] DEFAULT NULL::text[], content_encoding text DEFAULT NULL::text);

Machtigingen

Elke gebruiker of rol kan deze functie aanroepen.

Argumenten

scheidingsteken

null_string

koptekst

boolean vlag die aangeeft of het bestand een koptekstregel bevat met de namen van elke kolom in het bestand. In de uitvoer bevat de eerste regel de kolomnamen uit de tabel.

citaat

escape

force_quote

text[] dwingt het quoteren voor alle niet-NULL-waarden in elke opgegeven kolom te gebruiken. Null-uitvoer wordt nooit geciteerd. Als * is opgegeven, worden niet-NULL-waarden in alle kolommen vermeld.

force_not_null

force_null

content_encoding

text naam van de codering waarmee het bestand is gecodeerd. Als de optie wordt weggelaten, wordt de huidige clientcodering gebruikt.

Retourtype

jsonb

azure_storage.options_tsv

Functie die fungeert als een hulpprogrammafunctie, die kan worden aangeroepen als een parameter binnen blob_get, en is handig voor het decoderen van de inhoud van een tsv-bestand.

azure_storage.options_tsv(delimiter text DEFAULT NULL::text, null_string text DEFAULT NULL::text, content_encoding text DEFAULT NULL::text);

Machtigingen

Elke gebruiker of rol kan deze functie aanroepen.

Argumenten

scheidingsteken

null_string

content_encoding

text naam van de codering waarmee het bestand is gecodeerd. Als de optie wordt weggelaten, wordt de huidige clientcodering gebruikt.

Retourtype

jsonb

azure_storage.options_binary

Functie die fungeert als een hulpprogrammafunctie, die kan worden aangeroepen als een parameter binnen blob_get, en is handig voor het decoderen van de inhoud van een binair bestand.

azure_storage.options_binary(content_encoding text DEFAULT NULL::text);

Machtigingen

Elke gebruiker of rol kan deze functie aanroepen.

Argumenten

content_encoding

text naam van de codering waarmee het bestand is gecodeerd. Als de optie wordt weggelaten, wordt de huidige clientcodering gebruikt.

Retourtype

jsonb

Mogelijke fouten

FOUT: azure_storage: Machtiging is niet voldoende om de aangevraagde bewerking uit te voeren

Wanneer u een van de functies uitvoert die communiceren met Azure Storage (azure_storage.blob_listazure_storage.blob_getofazure_storage.blob_put) en de door het systeem toegewezen beheerde identiteit niet de juiste gegevensvlakrollen of -machtigingen krijgt (doorgaans een minimum van Inzender voor opslagblobgegevens voor azure_storage.blob_put en minimaal de opslagblobgegevenslezer voor de andere twee functies).

Het kan ook het geval zijn dat u de minimaal vereiste machtigingen al hebt verleend, maar deze nog niet van kracht zijn. Het kan enkele minuten duren voordat deze machtigingen worden doorgegeven.

FOUT: azure_storage: ontbrekende opslagreferenties

Bij het uitvoeren van een van de functies die communiceren met Azure Storage (azure_storage.blob_listazure_storage.blob_getof azure_storage.blob_put) en de referenties waarmee u de extensie wilt verifiëren met het opslagaccount, worden niet geregistreerd met behulp vanazure_storage.account_add.

FOUT: azure_storage: interne fout tijdens het verbinden

Wanneer het exemplaar van flexibele server het doelopslagaccount niet kan bereiken. Dat kan gebeuren in de volgende gevallen:

Het opslagaccount bestaat niet.
Netwerkconfiguratie staat niet toe dat verkeer afkomstig is van het exemplaar van flexibele server om het opslagaccount te bereiken. Wanneer het exemplaar van een flexibele server bijvoorbeeld wordt geïmplementeerd met openbare toegangsnetwerken en het opslagaccount alleen toegankelijk is via privé-eindpunten.

Wanneer de door het systeem toegewezen beheerde identiteit niet is ingeschakeld in het exemplaar van een flexibele server.

FOUT: azure_storage: ongeldige indeling voor opslagreferenties

Wanneer de door het systeem toegewezen beheerde identiteit is ingeschakeld op het exemplaar van Flexibele server, maar de server niet opnieuw is opgestart nadat deze is ingeschakeld.

FOUT: azure_storage: huidige gebruiker <user_or_role> mag geen opslagaccount <gebruiken account_name>

Bij het uitvoeren van een van de functies die communiceren met Azure Storage (azure_storage.blob_listazure_storage.blob_getof azure_storage.blob_put) met een gebruiker of rol die geen lid is van azure_storage_admin en waarvoor geen machtigingen zijn verleend, met behulp van azure_storage.account_user_add, om het bedoelde opslagaccount te gebruiken.

Voorbeelden

U moet voldoen aan de volgende vereisten voordat u de volgende voorbeelden kunt uitvoeren:

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:

resource_group=<resource_group>
location=<location>
storage_account=<account_name>
blob_container=<container_name>
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

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 naarmate 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 -O https://examples.citusdata.com/tutorial/events.csv
gzip -k events.csv
cp events.csv events_blob_without_extension
cp events.csv events_pipe.csv
cp events.csv.gz events_compressed
sed -i 's/,/|/g' events_pipe.csv
az storage blob upload-batch --account-name $storage_account --destination $blob_container --source . --pattern "events*" --account-key $access_key --overwrite --output none --only-show-errors

Notitie

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.

Tabel maken waarin gegevens worden geladen

Laten we de tabel maken waarin we de inhoud van het CSV-bestand importeren dat we hebben geüpload naar het opslagaccount. Hiervoor maakt u verbinding met uw exemplaar van Azure Database for PostgreSQL flexibele server met behulp PgAdminvan, psqlof de client van uw voorkeur en voert u de volgende instructie uit:

CREATE TABLE IF NOT EXISTS events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

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

Tip

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

Verwijzing naar opslagaccount verwijderen

In dit voorbeeld ziet u hoe u verwijzingen naar een opslagaccount verwijdert, zodat geen enkele gebruiker in de huidige database de azure_storage extensiefunctionaliteit kan gebruiken voor toegang tot dat opslagaccount.

SELECT azure_storage.account_remove('<account_name>');

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

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

SELECT * FROM azure_storage.account_user_remove('<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>');

De objecten weergeven met een specifiek voorvoegsel voor de blobnaam

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

Inhoud lezen uit een blob in een container

De blob_get functie haalt de inhoud van één specifieke blob (events.csv in dit geval) op in de container waarnaar wordt verwezen <container_name> van de <account_name> opslag. 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 events 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.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
LIMIT 5;

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

SELECT * FROM azure_storage.blob_get('<account_name>','<container_name>','events.csv.gz')
AS res (
         event_id BIGINT
        ,event_type TEXT
        ,event_public BOOLEAN
        ,repo_id BIGINT
        ,payload JSONB
        ,repo JSONB
        ,user_id BIGINT
        ,org JSONB
        ,created_at TIMESTAMP WITHOUT TIME ZONE)
LIMIT 5;

De decoderoptie gebruiken

In dit voorbeeld ziet u het gebruik van de decoder optie. Normaal gesproken wordt de indeling afgeleid van de extensie van het bestand, maar wanneer de bestandsinhoud geen overeenkomende extensie heeft, kunt u het argument decoder doorgeven.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events_blob_without_extension'
        , NULL::events
        , decoder := 'csv')
LIMIT 5;

Compressie gebruiken met decoderoptie

In dit voorbeeld ziet u hoe u de gzip-compressie kunt afdwingen op een gecomprimeerde gzip-blob waarvan de naam niet eindigt op een .gz extensie.

SELECT * FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events_compressed'
        , NULL::events
        , decoder := 'csv'
        , compression := 'gzip')
LIMIT 5;

Gefilterde inhoud importeren en wijzigen voordat het wordt geladen vanuit csv-indelingsobject

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-',event_id::text) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
WHERE event_type='PushEvent'
LIMIT 5;

Query's uitvoeren op inhoud uit bestand met kopteksten, aangepaste scheidingstekens, 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>'
        ,'events_pipe.csv'
        ,NULL::events
        ,options := azure_storage.options_csv_get(delimiter := '|' , header := 'true')
        );

Aggregatiequery 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 event_type, COUNT(*) FROM azure_storage.blob_get
        ('<account_name>'
        ,'<container_name>'
        ,'events.csv'
        , NULL::events)
GROUP BY event_type
ORDER BY 2 DESC
LIMIT 5;

Gegevens importeren met een COPY-instructie

In het volgende voorbeeld ziet u het importeren van gegevens uit een blob met de naam events.csv 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 events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

Gebruik een COPY instructie om gegevens naar de doeltabel te kopiëren. Geef op dat de eerste rij kolomkoppen bevat.

COPY events
FROM 'https://<account_name>.blob.core.windows.net/<container_name>/events.csv'
WITH (FORMAT 'csv', header);

Inhoud schrijven naar een blob in een container

De blob_put functie bevat de inhoud van één specifieke blob (eventscopy.csvin dit geval) en uploadt deze naar de container van de <account_name> opslag waarnaar wordt verwezen<container_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 eventscopy.csv.

SELECT azure_storage.blob_put
        ('<account_name>'
        ,'<container_name>'
        ,'eventscopy.csv'
        , top_5_events)
FROM (SELECT * FROM azure_storage.blob_get
                     ('<account_name>'
                     ,'<container_name>'
                     ,'events.csv'
                     , NULL::events) LIMIT 5) AS top_5_events;

Gegevens exporteren met een COPY-instructie

In het volgende voorbeeld ziet u het exporteren van gegevens uit een tabel met de naam events, naar een blob met de naam events_exported.csv 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 events
        (
         event_id bigint
        ,event_type text
        ,event_public boolean
        ,repo_id bigint
        ,payload jsonb
        ,repo jsonb
        ,user_id bigint
        ,org jsonb
        ,created_at timestamp without time zone
        );

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-instructievoorbeeld om deze te vullen met de inhoud van de voorbeeldgegevensset.

Gebruik een COPY instructie om gegevens naar de doeltabel te kopiëren. Geef op dat de eerste rij kolomkoppen bevat.

COPY events
TO 'https://<account_name>.blob.core.windows.net/<container_name>/events_exported.csv'
WITH (FORMAT 'csv', header);

Delen via

Gegevens importeren en exporteren met behulp van azure_storage-extensie in Azure Database for PostgreSQL - Flexible Server

Overzicht van de procedure

Autorisatie gebruiken met Microsoft Entra-id

Autorisatie gebruiken met gedeelde sleutel

Functies

azure_storage.account_add

Machtigingen

Argumenten

account_name_p

account_key_p

account_config

Retourtype

azure_storage.account_options_managed_identity

Machtigingen

Argumenten

naam

type

Retourtype

azure_storage.account_options_credentials

Machtigingen

Argumenten

naam

aanmeldingsgegevens

type

Retourtype

azure_storage.account_options

Machtigingen

Argumenten

naam

auth_type

storage_type

aanmeldingsgegevens

Retourtype

azure_storage.account_remove

Machtigingen

Argumenten

account_name_p

Retourtype

azure_storage.account_user_add

Machtigingen

Argumenten

account_name_p

user_p

Retourtype

azure_storage.account_user_remove

Machtigingen

Argumenten

account_name_p

user_p

Retourtype

azure_storage.account_list

Machtigingen

Argumenten

Retourtype

azure_storage.blob_list

Machtigingen

Argumenten

account_name

container_name

voorvoegsel

Retourtype

path

bytes

last_modified

etag

content_type

content_encoding

content_hash

azure_storage.blob_get

Machtigingen

Argumenten

account_name

container_name

path

Rec

Decoder

compressie

Opties

Retourtype