Biblioteka klienta obiektów blob usługi Azure Storage dla języka JavaScript — wersja 12.17.0

Artykuł
01/10/2024

Azure Storage Blob to rozwiązanie firmy Microsoft do magazynowania obiektów dla chmury. Magazyn obiektów blob jest zoptymalizowany pod kątem przechowywania olbrzymich ilości danych bez struktury. Dane bez struktury są danymi, które nie są zgodne z żadnym modelem lub definicją danych, jak na przykład dane tekstowe lub binarne.

Ten projekt udostępnia bibliotekę klienta w języku JavaScript, która ułatwia korzystanie z usługi Microsoft Azure Storage Blob Service.

Użyj bibliotek klienckich w tym pakiecie, aby:

Pobieranie/ustawianie właściwości usługi Blob Service
Tworzenie/wyświetlanie/usuwanie kontenerów
Tworzenie/odczyt/lista/aktualizowanie/usuwanie blokowych obiektów blob
Tworzenie/odczyt/lista/aktualizowanie/usuwanie stronicowych obiektów blob
Tworzenie/odczyt/lista/aktualizowanie/usuwanie uzupełnialnych obiektów blob

Linki kluczowe

Wprowadzenie

Obecnie obsługiwane środowiska

Wersje LTS Node.js
Najnowsze wersje przeglądarek Safari, Chrome, Edge i Firefox.

Aby uzyskać więcej informacji, zobacz nasze zasady pomocy technicznej .

Wymagania wstępne

Instalowanie pakietu

Preferowanym sposobem instalowania biblioteki klienta obiektów blob usługi Azure Storage dla języka JavaScript jest użycie menedżera pakietów npm. Wpisz następujące polecenie w oknie terminalu:

npm install @azure/storage-blob

Uwierzytelnianie klienta

Usługa Azure Storage obsługuje kilka sposobów uwierzytelniania. Aby wchodzić w interakcje z usługą Azure Blob Storage, musisz utworzyć wystąpienie klienta usługi Storage — BlobServiceClient, ContainerClientlub BlobClient na przykład. Zobacz przykłady tworzenia elementu BlobServiceClient , aby dowiedzieć się więcej na temat uwierzytelniania.

Azure Active Directory
Klucz wspólny
Sygnatury dostępu współdzielonego

Azure Active Directory

Usługa Azure Blob Storage obsługuje używanie usługi Azure Active Directory do uwierzytelniania żądań w swoich interfejsach API. Pakiet @azure/identity udostępnia różne typy poświadczeń, których aplikacja może użyć do tego celu. Zobacz PLIK README, aby @azure/identity uzyskać więcej szczegółów i przykładów, aby rozpocząć pracę.

Zgodność

Ta biblioteka jest zgodna z Node.js i przeglądarkami oraz jest weryfikowana pod kątem wersji LTS Node.js (>=8.16.0) i najnowszych wersji przeglądarek Chrome, Firefox i Edge.

Procesy robocze sieci Web

Ta biblioteka wymaga, aby niektóre obiekty DOM były globalnie dostępne w przypadku użycia w przeglądarce, które procesy robocze sieci Web nie są domyślnie dostępne. Aby ta biblioteka działała w przypadku procesów roboczych sieci Web, konieczne będzie ich poliwypełnianie.

Aby uzyskać więcej informacji, zapoznaj się z naszą dokumentacją dotyczącą używania zestawu Azure SDK dla struktury JS w internetowych procesach roboczych

Ta biblioteka zależy od następujących interfejsów API DOM, które wymagają zewnętrznego wypełniania wielowydajnego podczas korzystania z procesów roboczych sieci Web:

Różnice między Node.js a przeglądarkami

Istnieją różnice między środowiskiem uruchomieniowym Node.js i przeglądarkami. Podczas rozpoczynania pracy z tą biblioteką należy zwrócić uwagę na interfejsy API lub klasy oznaczone jako "DOSTĘPNE TYLKO W środowisku uruchomieniowym NODE.JS" lub "TYLKO DOSTĘPNE W PRZEGLĄDARKACH".

Jeśli obiekt blob przechowuje skompresowane dane w formacie lub deflate w gzip formacie, a jego kodowanie zawartości jest odpowiednio ustawione, zachowanie pobierania różni się między Node.js a przeglądarkami. W Node.js klienci magazynu będą pobierać obiekt blob w skompresowanym formacie, podczas gdy w przeglądarkach dane zostaną pobrane w formacie nieskompresowany.

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w Node.js

Autoryzacja klucza współużytkowanego na podstawie nazwy konta i klucza konta
- StorageSharedKeyCredential
Generowanie sygnatury dostępu współdzielonego (SAS)
- generateAccountSASQueryParameters()
- generateBlobSASQueryParameters()
Równoległe przekazywanie i pobieranie. Należy pamiętać, że BlockBlobClient.uploadData() jest dostępny zarówno w Node.js, jak i w przeglądarkach.
- BlockBlobClient.uploadFile()
- BlockBlobClient.uploadStream()
- BlobClient.downloadToBuffer()
- BlobClient.downloadToFile()

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w przeglądarkach

Równoległe przekazywanie i pobieranie
- BlockBlobClient.uploadBrowserData()

Pakiet JavaScript

Aby użyć tej biblioteki klienta w przeglądarce, najpierw należy użyć narzędzia bundler. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów.

CORS

Musisz skonfigurować reguły współużytkowania zasobów między źródłami (CORS, Cross-Origin Resource Sharing) dla konta magazynu, jeśli trzeba je opracowywać dla przeglądarek. Przejdź do Azure Portal i Eksplorator usługi Azure Storage, znajdź konto magazynu, utwórz nowe reguły CORS dla usług blob/queue/file/table.

Można na przykład utworzyć następujące ustawienia mechanizmu CORS na potrzeby debugowania. Należy jednak dokładnie dostosować ustawienia zgodnie z wymaganiami w środowisku produkcyjnym.

Dozwolone źródła: *
Dozwolone czasowniki: DELETE,GET,HEAD,MERGE,POST,OPTIONS,PUT
Dozwolone nagłówki: *
Uwidocznione nagłówki: *
Maksymalny wiek (w sekundach): 86400

Kluczowe pojęcia

Przeznaczenie usługi Blob Storage:

Obsługiwanie obrazów i dokumentów bezpośrednio w przeglądarce.
Przechowywanie plików do dostępu rozproszonego.
Przesyłanie strumieniowe audio i wideo.
Zapisywanie plików dziennika.
Zapisywanie danych w celu tworzenia kopii zapasowych, przywracania, odzyskiwania po awarii i archiwizowania.
Przechowywanie danych w celu analizy w usłudze lokalnej lub hostowanej na platformie Azure.

Magazyn obiektów blob oferuje trzy typy zasobów:

Konto magazynu używane za pośrednictwemBlobServiceClient
Kontener na koncie magazynu używany za pośrednictwemContainerClient
Obiekt blob w kontenerze używanym za pośrednictwem polecenia BlobClient

Przykłady

Importowanie pakietu
Tworzenie klienta usługi blob
Tworzenie nowego kontenera
Wyświetlanie listy kontenerów
Tworzenie obiektu blob przez przekazanie danych
Wyświetlanie listy obiektów blob wewnątrz kontenera
Pobieranie obiektu blob i konwertowanie go na ciąg (Node.js)
Pobieranie obiektu blob i konwertowanie go na ciąg (przeglądarki)

Importowanie pakietu

Aby użyć klientów, zaimportuj pakiet do pliku:

const AzureStorageBlob = require("@azure/storage-blob");

Alternatywnie selektywnie zaimportuj tylko potrzebne typy:

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

Tworzenie klienta usługi blob

Wymaga BlobServiceClient adresu URL do usługi obiektów blob i poświadczeń dostępu. Opcjonalnie akceptuje również niektóre ustawienia w parametrze options .

z `DefaultAzureCredential@azure/identity` pakietu

Zalecany sposób utworzenia wystąpienia elementu BlobServiceClient

Konfiguracja: odwołanie — autoryzowanie dostępu do obiektów blob i kolejek za pomocą usługi Azure Active Directory z poziomu aplikacji klienckiej — /azure/storage/common/storage-auth-aad-app

Rejestrowanie nowej aplikacji usługi AAD i przyznawanie uprawnień dostępu do usługi Azure Storage w imieniu zalogowanego użytkownika
- Rejestrowanie nowej aplikacji w usłudze Azure Active Directory (w witrynie Azure-Portal) — /azure/active-directory/develop/quickstart-register-app
- API permissions W sekcji wybierz pozycję Add a permission i wybierz pozycję Microsoft APIs.
- Zaznacz Azure Storage pole wyboru obok user_impersonation pozycji , a następnie kliknij pozycję Add permissions. Umożliwi to aplikacji dostęp do usługi Azure Storage w imieniu zalogowanego użytkownika.
Udzielanie dostępu do danych obiektów blob platformy Azure za pomocą kontroli dostępu opartej na rolach w witrynie Azure Portal
- Role RBAC dla obiektów blob i kolejek — /azure/storage/common/storage-auth-aad-rbac-portal.
- W witrynie Azure Portal przejdź do swojego konta magazynu i przypisz rolę Współautor danych obiektu blob usługi Storage do zarejestrowanej aplikacji usługi AAD z Access control (IAM) karty (na pasku nawigacyjnym po lewej stronie konta magazynu w witrynie Azure-Portal).
Konfiguracja środowiska dla przykładu
- Na stronie przeglądu aplikacji usługi AAD zanotuj wartości CLIENT ID i TENANT ID. Na karcie "Certyfikaty & wpisy tajne" utwórz wpis tajny i zanotuj je w dół.
- Upewnij się, że masz AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET jako zmienne środowiskowe, aby pomyślnie wykonać przykład (może korzystać z pliku process.env).

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

// Enter your storage account name
const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

Zobacz przykład uwierzytelniania Azure AD, aby zapoznać się z kompletnym przykładem użycia tej metody.

[Uwaga — powyższe kroki dotyczą tylko Node.js]

korzystanie z parametry połączenia

Alternatywnie można utworzyć wystąpienie BlobServiceClient metody statycznej fromConnectionString() z pełnym parametry połączenia jako argumentem. (Parametry połączenia można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM NODE.JS]

const { BlobServiceClient } = require("@azure/storage-blob");

const connStr = "<connection string>";

const blobServiceClient = BlobServiceClient.fromConnectionString(connStr);

Z `StorageSharedKeyCredential`

Alternatywnie możesz utworzyć BlobServiceClient wystąpienie obiektu StorageSharedKeyCredential za pomocą elementu , przekazując argumenty account-name i account-key. (Nazwę konta i klucz konta można uzyskać w witrynie Azure Portal). [DOSTĘPNE TYLKO W ŚRODOWISKU URUCHOMIENIOWYM NODE.JS]

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

// Enter your storage account name and shared key
const account = "<account>";
const accountKey = "<accountkey>";

// Use StorageSharedKeyCredential with storage account and account key
// StorageSharedKeyCredential is only available in Node.js runtime, not in browsers
const sharedKeyCredential = new StorageSharedKeyCredential(account, accountKey);
const blobServiceClient = new BlobServiceClient(
  `https://${account}.blob.core.windows.net`,
  sharedKeyCredential
);

z tokenem SAS

Ponadto można utworzyć wystąpienie obiektu BlobServiceClient za pomocą sygnatur dostępu współdzielonego (SAS). Token SYGNATURy dostępu współdzielonego można uzyskać z witryny Azure Portal lub wygenerować przy użyciu polecenia generateAccountSASQueryParameters().

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";

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

Tworzenie nowego kontenera

Użyj polecenia BlobServiceClient.getContainerClient() , aby pobrać wystąpienie klienta kontenera, a następnie utworzyć nowy zasób kontenera.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  // Create a container
  const containerName = `newcontainer${new Date().getTime()}`;
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const createContainerResponse = await containerClient.create();
  console.log(`Create container ${containerName} successfully`, createContainerResponse.requestId);
}

main();

Wyświetlanie listy kontenerów

Użyj BlobServiceClient.listContainers() funkcji , aby iterować kontenery przy użyciu nowej for-await-of składni:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  let i = 1;
  let containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

Alternatywnie bez użycia polecenia for-await-of:

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  let i = 1;
  let iter = blobServiceClient.listContainers();
  let containerItem = await iter.next();
  while (!containerItem.done) {
    console.log(`Container ${i++}: ${containerItem.value.name}`);
    containerItem = await iter.next();
  }
}

main();

Ponadto stronicowanie jest obsługiwane również w przypadku wyświetlania listy za pośrednictwem polecenia byPage():

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

async function main() {
  let i = 1;
  for await (const response of blobServiceClient.listContainers().byPage({ maxPageSize: 20 })) {
    if (response.containerItems) {
      for (const container of response.containerItems) {
        console.log(`Container ${i++}: ${container.name}`);
      }
    }
  }
}

main();

Aby zapoznać się z kompletnym przykładem iterowania kontenerów, zobacz samples/v12/typescript/src/listContainers.ts.

Tworzenie obiektu blob przez przekazanie danych

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  const content = "Hello world!";
  const blobName = "newblob" + new Date().getTime();
  const blockBlobClient = containerClient.getBlockBlobClient(blobName);
  const uploadBlobResponse = await blockBlobClient.upload(content, content.length);
  console.log(`Upload block blob ${blobName} successfully`, uploadBlobResponse.requestId);
}

main();

Wyświetlanie listy obiektów blob wewnątrz kontenera

Podobnie jak w przypadku wyświetlania listy kontenerów.

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);

  let i = 1;
  let blobs = containerClient.listBlobsFlat();
  for await (const blob of blobs) {
    console.log(`Blob ${i++}: ${blob.name}`);
  }
}

main();

Aby zapoznać się z kompletnym przykładem iterowania obiektów blob, zobacz samples/v12/typescript/src/listBlobsFlat.ts.

Pobieranie obiektu blob i konwertowanie go na ciąg (Node.js)

const { DefaultAzureCredential } = require("@azure/identity");
const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account>";
const defaultAzureCredential = new DefaultAzureCredential();

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

const containerName = "<container name>";
const blobName = "<blob name>";

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In Node.js, get downloaded data by accessing downloadBlockBlobResponse.readableStreamBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = (
    await streamToBuffer(downloadBlockBlobResponse.readableStreamBody)
  ).toString();
  console.log("Downloaded blob content:", downloaded);

  // [Node.js only] A helper method used to read a Node.js readable stream into a Buffer
  async function streamToBuffer(readableStream) {
    return new Promise((resolve, reject) => {
      const chunks = [];
      readableStream.on("data", (data) => {
        chunks.push(data instanceof Buffer ? data : Buffer.from(data));
      });
      readableStream.on("end", () => {
        resolve(Buffer.concat(chunks));
      });
      readableStream.on("error", reject);
    });
  }
}

main();

Pobierz obiekt blob i przekonwertuj go na ciąg (przeglądarki).

Aby uzyskać więcej informacji na temat korzystania z tej biblioteki w przeglądarce, zapoznaj się z sekcją Pakiet języka JavaScript .

const { BlobServiceClient } = require("@azure/storage-blob");

const account = "<account name>";
const sas = "<service Shared Access Signature Token>";
const containerName = "<container name>";
const blobName = "<blob name>";

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

async function main() {
  const containerClient = blobServiceClient.getContainerClient(containerName);
  const blobClient = containerClient.getBlobClient(blobName);

  // Get blob content from position 0 to the end
  // In browsers, get downloaded data by accessing downloadBlockBlobResponse.blobBody
  const downloadBlockBlobResponse = await blobClient.download();
  const downloaded = await blobToString(await downloadBlockBlobResponse.blobBody);
  console.log("Downloaded blob content", downloaded);

  // [Browsers only] A helper method used to convert a browser Blob into string.
  async function blobToString(blob) {
    const fileReader = new FileReader();
    return new Promise((resolve, reject) => {
      fileReader.onloadend = (ev) => {
        resolve(ev.target.result);
      };
      fileReader.onerror = reject;
      fileReader.readAsText(blob);
    });
  }
}

main();

Kompletny przykład prostych scenariuszy znajduje się w pliku samples/v12/typescript/src/sharedKeyAuth.ts.

Rozwiązywanie problemów

Włączenie rejestrowania może pomóc odkryć przydatne informacje o błędach. Aby wyświetlić dziennik żądań i odpowiedzi HTTP, ustaw zmienną AZURE_LOG_LEVEL środowiskową na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel polecenie w pliku @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

Następne kroki

Więcej przykładów kodu:

Współtworzenie

Jeśli chcesz współtworzyć tę bibliotekę, przeczytaj przewodnik współtworzenia , aby dowiedzieć się więcej na temat tworzenia i testowania kodu.

Zapoznaj się również z przewodnikiem dotyczącym magazynu , aby uzyskać dodatkowe informacje na temat konfigurowania środowiska testowego dla bibliotek magazynu.

Wrażenia

Biblioteka klienta obiektów blob usługi Azure Storage dla języka JavaScript — wersja 12.17.0

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

Instalowanie pakietu

Uwierzytelnianie klienta

Azure Active Directory

Zgodność

Procesy robocze sieci Web

Różnice między Node.js a przeglądarkami

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w Node.js

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w przeglądarkach

Pakiet JavaScript

CORS

Kluczowe pojęcia

Przykłady

Importowanie pakietu

Tworzenie klienta usługi blob

z `DefaultAzureCredential@azure/identity` pakietu

korzystanie z parametry połączenia

Z `StorageSharedKeyCredential`

z tokenem SAS

Tworzenie nowego kontenera

Wyświetlanie listy kontenerów

Tworzenie obiektu blob przez przekazanie danych

Wyświetlanie listy obiektów blob wewnątrz kontenera

Pobieranie obiektu blob i konwertowanie go na ciąg (Node.js)

Pobierz obiekt blob i przekonwertuj go na ciąg (przeglądarki).

Rozwiązywanie problemów

Następne kroki

Współtworzenie

Opinia

Dodatkowe zasoby

Biblioteka klienta obiektów blob usługi Azure Storage dla języka JavaScript — wersja 12.17.0

Wprowadzenie

Obecnie obsługiwane środowiska

Wymagania wstępne

Instalowanie pakietu

Uwierzytelnianie klienta

Azure Active Directory

Zgodność

Procesy robocze sieci Web

Różnice między Node.js a przeglądarkami

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w Node.js

Funkcje, interfejsy, klasy lub funkcje dostępne tylko w przeglądarkach

Pakiet JavaScript

CORS

Kluczowe pojęcia

Przykłady

Importowanie pakietu

Tworzenie klienta usługi blob

z DefaultAzureCredential@azure/identity pakietu

korzystanie z parametry połączenia

Z StorageSharedKeyCredential

z tokenem SAS

Tworzenie nowego kontenera

Wyświetlanie listy kontenerów

Tworzenie obiektu blob przez przekazanie danych

Wyświetlanie listy obiektów blob wewnątrz kontenera

Pobieranie obiektu blob i konwertowanie go na ciąg (Node.js)

Pobierz obiekt blob i przekonwertuj go na ciąg (przeglądarki).

Rozwiązywanie problemów

Następne kroki

Współtworzenie

Opinia

Dodatkowe zasoby

z `DefaultAzureCredential@azure/identity` pakietu

Z `StorageSharedKeyCredential`