Rozpoczynanie pracy z usługami Azure Blob Storage i JavaScript

  • Artykuł

W tym artykule pokazano, jak nawiązać połączenie z usługą Azure Blob Storage przy użyciu biblioteki klienta usługi Azure Blob Storage w wersji 12 dla języka JavaScript. Po nawiązaniu połączenia kod może działać na kontenerach, obiektach blob i funkcjach usługi Blob Storage.

Przykładowe fragmenty kodu są dostępne w usłudze GitHub jako pliki Runnable Node.js.

Przykłady kodu | | źródłowego biblioteki źródłowej pakietu referencyjnego | interfejsu API (npm) | Prześlij opinię

Wymagania wstępne

konfigurowanie projektu

  1. Otwórz wiersz polecenia i przejdź do folderu projektu. Zmień YOUR-DIRECTORY nazwę folderu na:

    cd YOUR-DIRECTORY

  2. Jeśli nie masz package.json jeszcze pliku w katalogu, zainicjuj projekt w celu utworzenia pliku:

    npm init -y

  3. Zainstaluj bibliotekę klienta usługi Azure Blob Storage dla języka JavaScript:

    npm install @azure/storage-blob

  4. Jeśli chcesz używać połączeń bez hasła przy użyciu identyfikatora Entra firmy Microsoft, zainstaluj bibliotekę klienta tożsamości platformy Azure dla języka JavaScript:

    npm install @azure/identity

Autoryzowanie dostępu i nawiązywanie połączenia z usługą Blob Storage

Identyfikator entra firmy Microsoft zapewnia najbezpieczniejsze połączenie, zarządzając tożsamością połączenia (tożsamością zarządzaną). Ta funkcja bez hasła umożliwia tworzenie aplikacji, która nie wymaga żadnych wpisów tajnych (kluczy ani parametry połączenia) przechowywanych w kodzie.

Konfigurowanie dostępu tożsamości do chmury platformy Azure

Aby nawiązać połączenie z platformą Azure bez haseł, musisz skonfigurować tożsamość platformy Azure lub użyć istniejącej tożsamości. Po skonfigurowaniu tożsamości upewnij się, że przypisano odpowiednie role do tożsamości.

Aby autoryzować dostęp bez hasła za pomocą identyfikatora Entra firmy Microsoft, musisz użyć poświadczeń platformy Azure. Jakiego typu poświadczenia potrzebujesz, zależy od tego, gdzie działa aplikacja. Użyj tej tabeli jako przewodnika.

Środowisko Metoda
Środowisko programistyczne Visual Studio Code
Środowisko programistyczne Jednostka usługi
Aplikacje hostowane na platformie Azure Konfiguracja aplikacji hostowanych na platformie Azure
Lokalne Konfiguracja aplikacji lokalnej

Konfigurowanie ról konta magazynu

Zasób magazynu musi mieć co najmniej jedną z następujących ról RBAC platformy Azure przypisanych do zasobu tożsamości, z którym planujesz nawiązać połączenie. Skonfiguruj role usługi Azure Storage dla każdej tożsamości utworzonej w poprzednim kroku: Chmura platformy Azure, programowanie lokalne, środowisko lokalne.

Po zakończeniu instalacji każda tożsamość musi mieć co najmniej jedną z odpowiednich ról:

  • Rola dostępu do danych , taka jak:

    • Czytelnik danych obiektu blob usługi Storage
    • Współautor danych obiektu blob usługi Storage

  • Rola zasobu — taka jak:

    • Czytelnik
    • Współautor

Kompilowanie aplikacji

Podczas kompilowania aplikacji kod będzie współdziałać przede wszystkim z trzema typami zasobów:

  • Konto magazynu, które jest unikatową przestrzenią nazw najwyższego poziomu dla danych usługi Azure Storage.
  • Kontenery, które organizują dane obiektów blob na koncie magazynu.
  • Obiekty blob, które przechowują dane bez struktury, takie jak dane tekstowe i binarne.

Na poniższym diagramie przedstawiono relacje między tymi zasobami.

Diagram of Blob storage architecture

Każdy typ zasobu jest reprezentowany przez co najmniej jednego skojarzonego klienta języka JavaScript:

Klasa opis
BlobServiceClient Reprezentuje punkt końcowy usługi Blob Storage dla konta magazynu.
ContainerClient Umożliwia manipulowanie kontenerami usługi Azure Storage i ich obiektami blob.
Obiekt blobClient Umożliwia manipulowanie obiektami blob usługi Azure Storage.

Tworzenie obiektu BlobServiceClient

Obiekt BlobServiceClient jest najwyższym obiektem w zestawie SDK. Ten klient umożliwia manipulowanie usługą, kontenerami i obiektami blob.

Po skonfigurowaniu ról tożsamości konta usługi Azure Storage i środowiska lokalnego utwórz plik JavaScript zawierający @azure/identity pakiet. Utwórz poświadczenie, takie jak DefaultAzureCredential, aby zaimplementować połączenia bez hasła z usługą Blob Storage. Użyj tego poświadczenia, aby uwierzytelnić się za pomocą obiektu BlobServiceClient .

// connect-with-default-azure-credential.js
const { BlobServiceClient } = require('@azure/storage-blob');
const { DefaultAzureCredential } = require('@azure/identity');
require('dotenv').config()

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error('Azure Storage accountName not found');

const blobServiceClient = new BlobServiceClient(
  `https://${accountName}.blob.core.windows.net`,
  new DefaultAzureCredential()
);

async function main(){
  
  const containerName = 'REPLACE-WITH-EXISTING-CONTAINER-NAME';
  const blobName = 'REPLACE-WITH-EXISTING-BLOB-NAME';

  const timestamp = Date.now();
  const fileName = `my-new-file-${timestamp}.txt`;

  // create container client
  const containerClient = await blobServiceClient.getContainerClient(containerName);

  // create blob client
  const blobClient = await containerClient.getBlockBlobClient(blobName);

  // download file
  await blobClient.downloadToFile(fileName);

  console.log(`${fileName} downloaded`);
  
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(`error: ${ex.message}`));

Pakiet dotenv służy do odczytywania nazwy konta magazynu z .env pliku. Nie należy zaewidencjonować tego pliku w kontroli źródła. Jeśli używasz lokalnej jednostki usługi w ramach konfiguracji DefaultAzureCredential, wszystkie informacje o zabezpieczeniach dla tego poświadczenia również zostaną wprowadzone do .env pliku.

Jeśli planujesz wdrożyć aplikację na serwerach i klientach uruchomionych poza platformą Azure, utwórz jedno z poświadczeń spełniających Twoje potrzeby.

Tworzenie obiektu ContainerClient

Obiekt ContainerClient można utworzyć z obiektu BlobServiceClient lub bezpośrednio.

Tworzenie obiektu ContainerClient z obiektu BlobServiceClient

Utwórz obiekt ContainerClient z obiektu BlobServiceClient.

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  BlobServiceClient,
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;

// Create BlobServiceClient
const blobServiceClient = new BlobServiceClient(
  `${baseUrl}`,
  sharedKeyCredential
);

async function main() {
  try {
    // Create container client
    const containerClient = await blobServiceClient.getContainerClient(
      containerName
    );

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
      console.log(`Blob ${i++}: ${blob.name}`);
    }
  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Bezpośrednie tworzenie elementu ContainerClient

// Azure Storage dependency
const {
  ContainerClient
} = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Unique container name
const timeStamp = Date.now();
const containerName = `test`;

async function main() {
  try {
    
    // create container client from DefaultAzureCredential
    const containerClient = new ContainerClient(
      `${baseUrl}/${containerName}`,
      new DefaultAzureCredential()
    );    

    // do something with containerClient...
    let i = 1;

    // List blobs in container
    for await (const blob of containerClient.listBlobsFlat()) {
        console.log(`Blob ${i++}: ${blob.name}`);
    }


  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Pakiet dotenv służy do odczytywania nazwy konta magazynu z .env pliku. Nie należy zaewidencjonować tego pliku w kontroli źródła.

Tworzenie obiektu BlobClient

Możesz utworzyć dowolne obiekty BlobClient wymienione poniżej z klasy ContainerClient lub bezpośrednio.

Lista klientów obiektów blob:

Tworzenie obiektu BlobClient z obiektu ContainerClient

// Azure Storage dependency
const {
  StorageSharedKeyCredential,
  ContainerClient
} = require("@azure/storage-blob");

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure Storage resource key
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY;
if (!accountKey) throw Error("Azure Storage accountKey not found");

// Create credential
const sharedKeyCredential = new StorageSharedKeyCredential(
  accountName,
  accountKey
);

const baseUrl = `https://${accountName}.blob.core.windows.net`;
const containerName = `my-container`;
const blobName = `my-blob`;

// Create ContainerClient
const containerClient = new ContainerClient(
  `${baseUrl}/${containerName}`,
  sharedKeyCredential
);  

async function main() {
  try {
  
    // Create BlobClient object
    const blobClient = containerClient.getBlobClient(blobName);

    // do something with blobClient...
    const properties = await blobClient.getProperties();
    console.log(`Blob ${blobName} properties:`);

    // get BlockBlobClient from blobClient
    const blockBlobClient = blobClient.getBlockBlobClient();

    // do something with blockBlobClient...
    const downloadResponse = await blockBlobClient.download(0);

  } catch (err) {
    console.log(err);
    throw err;
  }
}

main()
  .then(() => console.log(`done`))
  .catch((ex) => console.log(ex.message));

Bezpośrednie tworzenie obiektu blobClient

// Azure Storage dependency
const { BlockBlobClient } = require("@azure/storage-blob");

// Azure authentication for credential dependency
const { DefaultAzureCredential } = require('@azure/identity');

// For development environment - include environment variables from .env
require("dotenv").config();

// Azure Storage resource name
const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME;
if (!accountName) throw Error("Azure Storage accountName not found");

// Azure SDK needs base URL
const baseUrl = `https://${accountName}.blob.core.windows.net`;

// Container must exist prior to running this script
const containerName = `test`;

// Random blob name and contents
const timeStamp = Date.now();
const blobName = `${timeStamp}-my-blob.txt`;
const fileContentsAsString = "Hello there.";

async function main(){

  // Create a client that can authenticate with Azure Active Directory
  const client = new BlockBlobClient(
    `${baseUrl}/${containerName}/${blobName}`,
    new DefaultAzureCredential()
  );

  // Get file url - available before contents are uploaded
  console.log(`blob.url: ${client.url}`);

  // Upload file contents
  const result = await client.upload(fileContentsAsString, fileContentsAsString.length);

  // Get results
  return result;
}

main().then((result) => console.log(result)).catch((ex) => console.log(ex.message));

/*

Response looks like this:

{
  etag: '"0x8DAD247F1F4896E"',
  lastModified: 2022-11-29T20:26:07.000Z,
  contentMD5: <Buffer 9d 6a 29 63 87 20 77 db 67 4a 27 a3 9c 49 2e 61>,
  clientRequestId: 'a07fdd1f-5937-44c7-984f-0699a48a05c0',
  requestId: '3580e726-201e-0045-1a30-0474f6000000',
  version: '2021-04-10',
  date: 2022-11-29T20:26:06.000Z,
  isServerEncrypted: true,
  'content-length': '0',
  server: 'Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0',
  'x-ms-content-crc64': 'BLv7vb1ONT8=',
  body: undefined
}
*/

Pakiet dotenv służy do odczytywania nazwy konta magazynu z .env pliku. Nie należy zaewidencjonować tego pliku w kontroli źródła.

Zobacz też