Przekazywanie, pobieranie i wyświetlanie listy obiektów BLOB przy użyciu biblioteki klienckiej środowiska Node. jsUpload, download, and list blobs using the client library for Node.js

W tym przewodniku krok po kroku dowiesz się, jak używać biblioteki klienckiej programu Node. js v2 do przekazywania, pobierania i wyświetlania listy obiektów BLOB za pomocą usługi Azure Blob Storage.In this how-to guide, you learn how to use the client library for Node.js v2 to upload, download, and list blobs with Azure Blob storage.

Porada

Najnowsza wersja biblioteki klienta usługi Azure Storage dla środowiska Node. js to V10.The latest version of the Azure Storage client library for Node.js is v10. Firma Microsoft zaleca, aby użyć najnowszej wersji biblioteki klienta, gdy jest to możliwe.Microsoft recommends that you use the latest version of the client library when possible. Aby rozpocząć korzystanie z usługi V10, zobacz Szybki Start: Przekazuj, pobieraj, Wyświetlaj i usuwaj obiekty blob przy użyciu biblioteki klienta usługi Azure Storage dlajęzyka JavaScript v10 (wersja zapoznawcza).To get started using v10, see Quickstart: Upload, download, list, and delete blobs using Azure Storage client library for JavaScript v10 (preview).

Wymagania wstępnePrerequisites

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto.If you don't have an Azure subscription, create a free account before you begin.

Utwórz konto usługi Azure Storage w Azure Portal.Create an Azure storage account in the Azure portal. Aby uzyskać pomoc przy tworzeniu konta, zobacz Tworzenie konta magazynu.For help creating the account, see Create a storage account.

Pobieranie przykładowej aplikacjiDownload the sample application

Przykładowa aplikacja jest prostą aplikacją konsolową Node. js.The sample application is a simple Node.js console application. Aby rozpocząć, sklonuj repozytorium na swoją maszynę przy użyciu następującego polecenia:To begin, clone the repository to your machine using the following command:

git clone https://github.com/Azure-Samples/storage-blobs-node-quickstart.git

Aby otworzyć tę aplikację, wyszukaj folder storage-blobs-node-quickstart i otwórz go w środowisku edycji kodu.To open the application, look for the storage-blobs-node-quickstart folder and open it in your favorite code editing environment.

Kopiowanie poświadczeń z witryny Azure PortalCopy your credentials from the Azure portal

Aplikacja przykładowa musi uwierzytelnić dostęp do konta magazynu.The sample application needs to authenticate access to your storage account. W celu uwierzytelnienia dodaj do aplikacji poświadczenia konta magazynu w postaci parametrów połączenia.To authenticate, add your storage account credentials to the application as a connection string. Wyświetl poświadczenia konta magazynu, wykonując następujące czynności:View your storage account credentials by following these steps:

  1. Zaloguj się w witrynie Azure Portal.Sign in to the Azure portal.

  2. Odszukaj konto magazynu.Locate your storage account.

  3. W sekcji Ustawienia omówienia kont magazynu wybierz pozycję Klucze dostępu.In the Settings section of the storage account overview, select Access keys. W tym miejscu możesz przeglądać klucze dostępu do konta oraz pełne parametry połączenia dla każdego klucza.Here, you can view your account access keys and the complete connection string for each key.

  4. Znajdź wartość Parametry połączenia w obszarze key1 i wybierz przycisk Kopiuj, aby skopiować parametry połączenia.Find the Connection string value under key1, and select the Copy button to copy the connection string. W następnym kroku dodasz wartość parametrów połączenia do zmiennej środowiskowej.You will add the connection string value to an environment variable in the next step.

    Zrzut ekranu pokazujący sposób kopiowania parametrów połączenia z witryny Azure Portal

Konfigurowanie parametrów połączenia magazynuConfigure your storage connection string

Aby uruchomić aplikację, musisz wprowadzić parametry połączenia konta magazynu.Before running the application, you must provide the connection string for your storage account. Przykładowe repozytorium zawiera plik o nazwie .env.example.The sample repository includes a file named .env.example. Zmień nazwę tego pliku, usuwając rozszerzenie .example, aby otrzymać plik o nazwie .env.You can rename this file by removing the .example extension, which results in a file named .env. W pliku .env dodaj wartość parametrów połączenia po kluczu AZURE_STORAGE_CONNECTION_STRING.Inside the .env file, add your connection string value after the AZURE_STORAGE_CONNECTION_STRING key.

Instalowanie wymaganych pakietówInstall required packages

W katalogu aplikacji uruchom polecenie npm install, aby zainstalować pakiety wymagane przez aplikację.In the application directory, run npm install to install the required packages for the application.

npm install

Uruchamianie aplikacji przykładowejRun the sample

Po zainstalowaniu zależności możesz uruchomić przykład, wykonując następujące polecenie:Now that the dependencies are installed, you can run the sample by issuing the following command:

npm start

Dane wyjściowe skryptu będą mieć postać podobną do następującej:The output from the script will be similar to the following:

Containers:
 - container-one
 - container-two
Container "demo" is created
Blob "quickstart.txt" is uploaded
Local file "./readme.md" is uploaded
Blobs in "demo" container:
 - quickstart.txt
 - readme.md
Blob downloaded blob content: "hello Blob SDK"
Blob "quickstart.txt" is deleted
Container "demo" is deleted
Done

Jeśli na potrzeby tego przykładu używasz nowego konta magazynu, nazwy kontenerów mogą nie być wyświetlane w obszarze etykieta "kontenery".If you are using a new storage account for this example, then you may not see any container names listed under the label "Containers".

Omówienie koduUnderstanding the code

Pierwsze wyrażenie jest używane do ładowania wartości do zmiennych środowiskowych.The first expression is used to load values into environment variables.

if (process.env.NODE_ENV !== 'production') {
    require('dotenv').load();
}

Moduł dotenv ładuje zmienne środowiskowe podczas uruchamiania aplikacji lokalnie na potrzeby debugowania.The dotenv module loads environment variables when running the app locally for debugging. Wartości są definiowane w pliku env i ładowane do bieżącego kontekstu wykonania.Values are defined in a file named .env and loaded into the current execution context. W kontekstach produkcyjnych konfiguracja serwera udostępnia te wartości, dlatego ten kod jest uruchamiany tylko wtedy, gdy skrypt działa w kontekście innym niż „produkcja”.In production contexts, the server configuration provides these values and that is why this code is only run when the script is not running under a "production" context.

const path = require('path');
const storage = require('azure-storage');

Poniżej przedstawiono funkcje tych modułów:The purpose of the modules is as follows:

plik o nazwie env do bieżącego kontekstu wykonywaniafile named .env into the current execution context

  • path — jest wymagany do określenia ścieżki bezwzględnej do pliku przekazywanego do magazynu obiektów blobpath is required in order to determine the absolute file path of the file to upload to blob storage
  • Azure-Storage to moduł biblioteki klienta usługi Azure Storage dla środowiska Node. jsazure-storage is the Azure Storage client library module for Node.js

Następnie zmienna blobService jest inicjowana jako nowe wystąpienie usługi Azure Blob Service.Next, the blobService variable is initialized as a new instance of the Azure Blob service.

const blobService = storage.createBlobService();

W poniższej implementacji każda funkcja blobService jest opakowana w obiekt Promise. Pozwala to korzystać z funkcji async i operatora await języka JavaScript w celu usprawnienia wywołań zwrotnych interfejsu API usługi Azure Storage.In the following implementation, each of the blobService functions is wrapped in a Promise, which allows access to JavaScript's async function and await operator to streamline the callback nature of the Azure Storage API. Jeśli poszczególne funkcje zwrócą pomyślne odpowiedzi, obiekt Promise wskazuje na właściwe dane i komunikat specyficzny dla akcji.When a successful response returns for each function, the promise resolves with relevant data along with a message specific to the action.

Wyświetlanie listy kontenerówList containers

Funkcja listContainers wywołuje element listContainersSegmented, który zwraca kolekcje kontenerów w grupach.The listContainers function calls listContainersSegmented which returns collections of containers in groups.

const listContainers = async () => {
    return new Promise((resolve, reject) => {
        blobService.listContainersSegmented(null, (err, data) => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `${data.entries.length} containers`, containers: data.entries });
            }
        });
    });
};

Rozmiar grup można konfigurować za pomocą elementu ListContainersOptions.The size of the groups is configurable via ListContainersOptions. Wywołanie metody listContainersSegmented zwraca metadane obiektu blob jako tablicę wystąpień klasy ContainerResult.Calling listContainersSegmented returns blob metadata as an array of ContainerResult instances. Wyniki są zwracane w partiach inkrementowanych o 5000 (segmenty).Results are returned in 5,000 increment batches (segments). Jeśli kontener zawiera ponad 5000 obiektów blob, do wyników jest dołączana wartość tokenu kontynuacji.If there are more than 5,000 blobs in a container, then the results include a value for continuationToken. Aby wyświetlić listę kolejnych segmentów z kontenera obiektów blob, można przekazać token kontynuacji do metody listContainersSegment jako drugi argument.To list subsequent segments from the blob container, you can pass the continuation token back into listContainersSegment as the second argument.

Tworzenie konteneraCreate a container

Funkcja createContainer wywołuje funkcję createContainerIfNotExists i ustawia odpowiedni poziom dostępu dla obiektu blob.The createContainer function calls createContainerIfNotExists and sets the appropriate access level for the blob.

const createContainer = async (containerName) => {
    return new Promise((resolve, reject) => {
        blobService.createContainerIfNotExists(containerName, { publicAccessLevel: 'blob' }, err => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `Container '${containerName}' created` });
            }
        });
    });
};

Drugi parametr — (options) — funkcji createContainerIfNotExists przyjmuje wartość publicAccessLevel.The second parameter (options) for createContainerIfNotExists accepts a value for publicAccessLevel. Wartość blob parametru publicAccessLevel określa, że dane konkretnego obiektu blob są dostępne publicznie.The value blob for publicAccessLevel specifies that specific blob data is exposed to the public. To ustawienie jest inne niż poziom dostępu container, który umożliwia wyświetlanie zawartości kontenera.This setting is in contrast to container level access, which grants the ability to list the contents of the container.

Użycie funkcji createContainerIfNotExists pozwala aplikacji wielokrotnie uruchamiać polecenie createContainer bez zwracania błędów, jeśli kontener już istnieje.The use of createContainerIfNotExists allows the application to run the createContainer command multiple times without returning errors when the container already exists. W środowisku produkcyjnym funkcja createContainerIfNotExists zwykle jest wywoływana tylko raz, ponieważ w całej aplikacji jest używany ten sam kontener.In a production environment, you often only call createContainerIfNotExists once as the same container is used throughout the application. W takiej sytuacji można wcześniej utworzyć kontener za pośrednictwem portalu lub przy użyciu interfejsu wiersza polecenia platformy Azure.In these cases, you can create the container ahead of time through the portal or via the Azure CLI.

Przekazywanie tekstuUpload text

Funkcja uploadString wywołuje element createBlockBlobFromText w celu zapisania (lub nadpisania) dowolnego ciągu w kontenerze obiektów blob.The uploadString function calls createBlockBlobFromText to write (or overwrite) an arbitrary string to the blob container.

const uploadString = async (containerName, blobName, text) => {
    return new Promise((resolve, reject) => {
        blobService.createBlockBlobFromText(containerName, blobName, text, err => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `Text "${text}" is written to blob storage` });
            }
        });
    });
};

Przekazywanie pliku lokalnegoUpload a local file

Za pomocą funkcji createBlockBlobFromLocalFile funkcja uploadLocalFile przekazuje plik z systemu plików do magazynu obiektów blob i go zapisuje lub nadpisuje.The uploadLocalFile function uses createBlockBlobFromLocalFile to upload and write (or overwrite) a file from the file system into blob storage.

const uploadLocalFile = async (containerName, filePath) => {
    return new Promise((resolve, reject) => {
        const fullPath = path.resolve(filePath);
        const blobName = path.basename(filePath);
        blobService.createBlockBlobFromLocalFile(containerName, blobName, fullPath, err => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `Local file "${filePath}" is uploaded` });
            }
        });
    });
};

Inne metody przekazywania zawartości do obiektów blob obejmują użycie tekstu i strumieni.Other approaches available to upload content into blobs include working with text and streams. Aby sprawdzić, czy plik został przekazany do magazynu obiektów blob, można użyć Eksploratora usługi Azure Storage w celu wyświetlenia danych na koncie.To verify the file is uploaded to your blob storage, you can use the Azure Storage Explorer to view the data in your account.

Wyświetlanie listy obiektów blobList the blobs

Funkcja listBlobs wywołuje metodę listBlobsSegmented w celu zwrócenia listy metadanych obiektu blob w kontenerze.The listBlobs function calls the listBlobsSegmented method to return a list of blob metadata in a container.

const listBlobs = async (containerName) => {
    return new Promise((resolve, reject) => {
        blobService.listBlobsSegmented(containerName, null, (err, data) => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `${data.entries.length} blobs in '${containerName}'`, blobs: data.entries });
            }
        });
    });
};

Metoda listBlobsSegmented zwraca metadane obiektu blob jako tablicę wystąpień klasy BlobResult.Calling listBlobsSegmented returns blob metadata as an array of BlobResult instances. Wyniki są zwracane w partiach inkrementowanych o 5000 (segmenty).Results are returned in 5,000 increment batches (segments). Jeśli kontener zawiera ponad 5000 obiektów blob, do wyników jest dołączana wartość tokenu kontynuacji.If there are more than 5,000 blobs in a container, then the results include a value for continuationToken. Aby wyświetlić listę kolejnych segmentów z kontenera obiektów blob, można przekazać token kontynuacji do metody listBlobsSegmented jako drugi argument.To list subsequent segments from the blob container, you can pass the continuation token back into listBlobSegmented as the second argument.

Pobieranie obiektu blobDownload a blob

Za pomocą funkcji getBlobToText funkcja downloadBlob pobiera zawartość obiektu blob do danej ścieżki bezwzględnej do pliku.The downloadBlob function uses getBlobToText to download the contents of the blob to the given absolute file path.

const downloadBlob = async (containerName, blobName) => {
    const dowloadFilePath = path.resolve('./' + blobName.replace('.txt', '.downloaded.txt'));
    return new Promise((resolve, reject) => {
        blobService.getBlobToText(containerName, blobName, (err, data) => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `Blob downloaded "${data}"`, text: data });
            }
        });
    });
};

Przedstawiona w tym miejscu implementacja zmienia źródło i zwraca zawartość obiektu blob jako ciąg.The implementation shown here changes the source returns the contents of the blob as a string. Możesz również pobrać obiekt blob jako strumień, a także bezpośrednio do pliku lokalnego.You can also download the blob as a stream as well as directly to a local file.

Usuwanie obiektu blobDelete a blob

Funkcja deleteBlob wywołuje funkcję deleteBlobIfExists.The deleteBlob function calls the deleteBlobIfExists function. Jak sugeruje jej nazwa, ta funkcja nie zwraca błędu, jeśli obiekt blob został już usunięty.As the name implies, this function does not return an error if the blob is already deleted.

const deleteBlob = async (containerName, blobName) => {
    return new Promise((resolve, reject) => {
        blobService.deleteBlobIfExists(containerName, blobName, err => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `Block blob '${blobName}' deleted` });
            }
        });
    });
};

Usuwanie konteneraDelete a container

Kontenery są usuwane przez wywołanie metody deleteContainer z usługi obiektów blob i przekazanie nazwy kontenera.Containers are deleted by calling the deleteContainer method off the blob service and passing in the container name.

const deleteContainer = async (containerName) => {
    return new Promise((resolve, reject) => {
        blobService.deleteContainer(containerName, err => {
            if (err) {
                reject(err);
            } else {
                resolve({ message: `Container '${containerName}' deleted` });
            }
        });
    });
};

Kod wywołującyCalling code

Aby umożliwić obsługę składni async/await języka JavaScript, cały kod wywołujący został opakowany w funkcję o nazwie execute.In order to support JavaScript's async/await syntax, all the calling code is wrapped in a function named execute. Następnie funkcja execute jest wywoływana i obsługiwana jako obietnica.Then execute is called and handled as a promise.

async function execute() {
    // commands 
}

execute().then(() => console.log("Done")).catch((e) => console.log(e));

Cały poniższy kod jest wywoływany wewnątrz funkcji execute, w której umieszczono komentarz // commands.All of the following code runs inside the execute function where the // commands comment is placed.

Najpierw odpowiednie zmienne są deklarowane w celu przypisania nazw, utworzenia przykładu zawartości oraz wskazania pliku lokalnego do przekazania do magazynu obiektów blob.First, the relevant variables are declared to assign names, sample content and to point to the local file to upload to Blob storage.

const containerName = "demo";
const blobName = "quickstart.txt";
const content = "hello Node SDK";
const localFilePath = "./readme.md";
let response;

Aby wyświetlić listę kontenerów na koncie magazynu, jest wywoływana funkcja listContainers, a zwrócona lista kontenerów jest rejestrowana w oknie danych wyjściowych.To list the containers in the storage account, the listContainers function is called and the returned list of containers is logged to the output window.

console.log("Containers:");
response = await listContainers();
response.containers.forEach((container) => console.log(` -  ${container.name}`));

Po udostępnieniu listy kontenerów możesz użyć metody findIndex tablicy, aby zobaczyć, czy kontener, który chcesz utworzyć, już istnieje.Once the list of containers is available, then you can use the Array findIndex method to see if the container you want to create already exists. Jeśli kontener nie istnieje, zostanie on utworzony.If the container does not exist then the container is created.

const containerDoesNotExist = response.containers.findIndex((container) => container.name === containerName) === -1;

if (containerDoesNotExist) {
    await createContainer(containerName);
    console.log(`Container "${containerName}" is created`);
}

Następnie ciąg i lokalny plik są przekazywane do magazynu obiektów blob.Next, a string and a local file is uploaded to Blob storage.

await uploadString(containerName, blobName, content);
console.log(`Blob "${blobName}" is uploaded`);

response = await uploadLocalFile(containerName, localFilePath);
console.log(response.message);

Proces wyświetlania listy obiektów blob jest taki sam jak proces tworzenia listy kontenerów.The process to list blobs is the same as listing containers. Wywołanie do metody listBlobs zwraca tablicę obiektów blob w kontenerze. Obiekty te są rejestrowane w oknie danych wyjściowych.The call to listBlobs returns an array of blobs in the container and are logged to the output window.

console.log(`Blobs in "${containerName}" container:`);
response = await listBlobs(containerName);
response.blobs.forEach((blob) => console.log(` - ${blob.name}`));

Aby pobrać obiekt blob, odpowiedź jest przechwytywana i używana do uzyskiwania dostępu do wartości obiektu blob.To download a blob, the response is captured and used to access the value of the blob. Element readableStreamBody z odpowiedzi jest konwertowany na ciąg i rejestrowany w oknie danych wyjściowych.From the response readableStreamBody is converted to a string and logged out to the output window.

response = await downloadBlob(containerName, blobName);
console.log(`Downloaded blob content: "${response.text}"`);

Na koniec obiekt blob i kontener są usuwane z konta magazynu.Finally, the blob and container are deleted from the storage account.

await deleteBlob(containerName, blobName);
console.log(`Blob "${blobName}" is deleted`);

await deleteContainer(containerName);
console.log(`Container "${containerName}" is deleted`);

Oczyszczanie zasobówClean up resources

Wszystkie dane zapisane na koncie magazynu są automatycznie usuwane po zakończeniu pracy z przykładowym kodem.All data written to the storage account is automatically deleted at the end of the code sample.

Zasoby używane do tworzenia aplikacji Node.js z obiektami blobResources for developing Node.js applications with blobs

Zobacz dodatkowe zasoby używane podczas tworzenia aplikacji Node.js z magazynem obiektów blob:See these additional resources for Node.js development with Blob storage:

Pliki binarne i kod źródłowyBinaries and source code

Dokumentacja i przykłady dotyczące biblioteka klientaClient library reference and samples

Następne krokiNext steps

W tym artykule przedstawiono sposób przekazywania pliku między dyskiem lokalnym i usługą Azure Blob Storage przy użyciu środowiska Node. js.This article demonstrates how to upload a file between a local disk and Azure Blob storage using Node.js. Aby dowiedzieć się więcej na temat pracy z usługą Blob Storage, przejdź do repozytorium GitHub.To learn more about working with Blob storage, continue to the GitHub repository.