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

Azure Storage Blob to rozwiązanie magazynu obiektów firmy Microsoft dla chmury. Magazyn obiektów blob jest zoptymalizowany pod kątem przechowywania ogromnych ilości danych bez struktury. Dane bez struktury to dane, które nie są zgodne z określonym modelem lub definicją danych, takimi jak 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

• kod źródłowy
• pakiet (npm)
• Dokumentacja referencyjna interfejsu API
• dokumentacja produktu
• przykładów
• interfejsów API REST obiektów blob usługi Azure Storage

Wprowadzenie

Obecnie obsługiwane środowiska

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

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

Warunki wstępne

• subskrypcji platformy Azure
• Konto magazynu

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 móc korzystać z usługi Azure Blob Storage, musisz na przykład utworzyć wystąpienie klienta usługi Storage — BlobServiceClient, ContainerClientlub BlobClient. Zobacz przykłady tworzenia BlobServiceClient, aby dowiedzieć się więcej na temat uwierzytelniania.

• usługi Azure Active Directory
• klucza współużytkowanego
• 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. Aby uzyskać więcej szczegółów i przykładów, zobacz README dla @azure/identity.

Zgodność

Ta biblioteka jest zgodna z Node.js i przeglądarkami oraz jest weryfikowana w wersjach Node.js LTS (>=8.16.0) i najnowszych wersjach przeglądarki 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 procesach roboczych sieci Web, należy je polifill.

Aby uzyskać więcej informacji, zapoznaj się z naszą dokumentacją dotyczącą korzystania z zestawu Azure SDK for JS w Web Workers

Ta biblioteka zależy od następujących interfejsów API DOM, które wymagają zewnętrznych polifilli załadowanych podczas korzystania z procesów roboczych sieci Web:

• document
• DOMParser
• Node
• XMLSerializer

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

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

• Jeśli obiekt blob przechowuje skompresowane dane w formacie gzip lub deflate, 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 formacie skompresowanym, 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ępna 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ć pakietu. Aby uzyskać szczegółowe informacje o tym, jak to zrobić, zapoznaj się z naszą dokumentacją dotyczącą tworzenia pakietów .

MECHANIZM CORS

Musisz skonfigurować współużytkowanie zasobów między źródłami (CORS) regułami dla konta magazynu, jeśli chcesz utworzyć aplikacje dla przeglądarek. Przejdź do witryny Azure Portal i Eksploratora 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

Usługa Blob Storage została zaprojektowana pod kątem:

• Obsługa obrazów lub dokumentów bezpośrednio w przeglądarce.
• Przechowywanie plików na potrzeby dostępu rozproszonego.
• Przesyłanie strumieniowe wideo i audio.
• Zapisywanie w plikach dziennika.
• Przechowywanie danych na potrzeby tworzenia kopii zapasowych i przywracania, odzyskiwania po awarii i archiwizowania.
• Przechowywanie danych na potrzeby analizy przez usługę lokalną lub hostowaną na platformie Azure.

Usługa Blob Storage oferuje trzy typy zasobów:

• Konto magazynu używane za pośrednictwem BlobServiceClient
• Kontener na koncie magazynu używanym za pośrednictwem ContainerClient
• blob w kontenerze używanym za pośrednictwem 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
• Pobierz obiekt blob i przekonwertuj go na ciąg (Node.js)
• Pobierz obiekt blob i przekonwertuj 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 obiektów blob

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

z DefaultAzureCredential z pakietu @azure/identity

Zalecany sposób tworzenia wystąpienia 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
  • W sekcji API permissions wybierz pozycję Add a permission i wybierz pozycję Microsoft APIs.
  • Wybierz Azure Storage i zaznacz pole wyboru obok user_impersonation, a następnie kliknij przycisk Add permissions. Umożliwiłoby 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 konta magazynu i przypisz rolę współautora danych obiektu blob usługi Storage do zarejestrowanej aplikacji usługi AAD z karty Access control (IAM) (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 CLIENT ID i TENANT ID. Na karcie "Certyfikaty & Wpisy tajne" utwórz wpis tajny i zanotuj je.
  • 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 Auth usługi Azure AD, aby zapoznać się z kompletnym przykładem użycia tej metody.

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

używanie parametrów połączenia

Alternatywnie można utworzyć wystąpienie BlobServiceClient przy użyciu metody statycznej fromConnectionString() z pełnymi parametrami 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 utworzysz wystąpienie BlobServiceClient przy użyciu StorageSharedKeyCredential, 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 BlobServiceClient przy użyciu sygnatur dostępu współdzielonego (SAS). Token SAS można uzyskać z witryny Azure Portal lub wygenerować go przy użyciu 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 BlobServiceClient.getContainerClient(), aby uzyskać wystąpienie klienta kontenera, a następnie utwórz 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 funkcji BlobServiceClient.listContainers(), aby iterować kontenery przy użyciu nowej składni 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 containers = blobServiceClient.listContainers();
  for await (const container of containers) {
    console.log(`Container ${i++}: ${container.name}`);
  }
}

main();

Alternatywnie bez użycia 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 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 uzyskać kompletny przykład dotyczący 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 uzyskać kompletny przykład dotyczący iterowania obiektów blob, zobacz samples/v12/typescript/src/listBlobsFlat.ts.

Pobierz obiekt blob i przekonwertuj 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ą pakietu 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 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ą środowiskową AZURE_LOG_LEVEL na info. Alternatywnie rejestrowanie można włączyć w czasie wykonywania, wywołując setLogLevel w @azure/logger:

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

setLogLevel("info");

Następne kroki

Więcej przykładów kodu:

• Blob Storage Samples (JavaScript)
• przykłady usługi Blob Storage (TypeScript)
• przypadki testowe usługi Blob Storage

Przyczyniając się

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

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