Použití sad Azure SDK pro JavaScript a TypeScript

  • Článek

Pokud chcete přistupovat ke službám Azure prostřednictvím kódu programu, použijte sady Azure SDK pro JavaScript. Tyto sady SDK jsou obvykle vymezeny oborem balíčku @azure npm publikovaným sadou azure-sdk.

Rozdíly mezi sadami SDK a rozhraními REST API

Následující informace vám porozumí, kdy použít typ přístupového mechanismu.

  • Sady Azure SDK jsou upřednostňovanou metodou přístupu ke službě Azure. Sady Azure SDK abstrahuje často používaný kód potřebný ke správě cloudových požadavků REST platformy Azure, jako jsou ověřování, opakování a protokolování.
  • Azure REST API jsou upřednostňovanou metodou, pokud jste:
    • Práce se službami Ve verzi Preview, které nemají dostupné sady Azure SDK Zvažte svůj kód jako verzi Preview, která by se měla aktualizovat, když je služba obecně dostupná se sadami SDK.
    • Chcete provádět volání REST přímo, protože nechcete, aby celá sada SDK používala jedno rozhraní REST API nebo chcete mít hlubší kontrolu nad požadavky HTTP.

Klientské knihovny a knihovny pro správu Azure

Verze sady Azure SDK jsou k dispozici takto:

  • Sady SDK pro správu: Knihovny pro správu umožňují zřizovat a spravovat prostředky Azure prostřednictvím Azure Resource Manageru (ARM). Tyto knihovny @azure/arm- můžete rozpoznat v jejich názvech balíčků.
  • Klientské sady SDK: Vzhledem k tomu, že prostředek Azure již existuje, použijete klientské knihovny k jeho využití a interakci s ním.
    • Každý balíček README.md zahrnuje dokumentaci a ukázky.

Instalace balíčků Azure npm

Sady Azure SDK jsou volně dostupné od NPM. Nainstalujte jednotlivé sady SDK potřebné. Každá sada SDK poskytuje definice TypeScriptu.

V případě použití klienta nebo prohlížeče je potřeba do procesu sdružování přidat sady SDK Azure.

Použití ukázkového kódu balíčku Azure npm

Každý balíček obsahuje dokumentaci, která vám umožní rychle začít s balíčkem. Informace o jejich používání najdete v konkrétních balíčcích NPM, které používáte.

Zadání přihlašovacích údajů pro ověřování

Sady Azure SDK vyžadují přihlašovací údaje k ověření na platformě Azure. Třídy přihlašovacích údajů poskytované @azure/identitou poskytují několik výhod:

  • Rychlé onboarding
  • Nejbezpečnější metoda
  • Oddělte ověřovací mechanismus od kódu. To vám umožní používat stejný kód místně a na platformě Azure, zatímco přihlašovací údaje se liší.
  • Zajištění zřetězených ověřování, aby bylo možné použít několik mechanismů

Vytvoření klienta sady SDK a metod volání

Po programovém vytvoření přihlašovacích údajů předejte přihlašovací údaje klientovi sady Azure SDK. Klient může vyžadovat další informace, jako je ID předplatného nebo adresa URL služby. Tyto hodnoty jsou k dispozici na webu Azure Portal pro váš prostředek.

Zobrazí seznam předplatných, ke kterým má tento přihlašovací údaj přístup ke čtení.

const {
  ClientSecretCredential,
  DefaultAzureCredential,
} = require("@azure/identity");
const { SubscriptionClient } = require("@azure/arm-subscriptions");
require("dotenv").config();

let credentials = null;

const tenantId = process.env["AZURE_TENANT_ID"];
const clientId = process.env["AZURE_CLIENT_ID"];
const secret = process.env["AZURE_CLIENT_SECRET"];

if (process.env.NODE_ENV && process.env.NODE_ENV === "production") {
  // production
  credentials = new DefaultAzureCredential();
} else {
  // development
  if (tenantId && clientId && secret) {
    console.log("development");
    credentials = new ClientSecretCredential(tenantId, clientId, secret);
  } else {
    credentials = new DefaultAzureCredential();
  }
}

async function listSubscriptions() {
  try {
    // use credential to authenticate with Azure SDKs
    const client = new SubscriptionClient(credentials);

    // get details of each subscription
    for await (const item of client.subscriptions.list()) {
      const subscriptionDetails = await client.subscriptions.get(
        item.subscriptionId
      );
      /* 
        Each item looks like:
      
        {
          id: '/subscriptions/123456',
          subscriptionId: '123456',
          displayName: 'YOUR-SUBSCRIPTION-NAME',
          state: 'Enabled',
          subscriptionPolicies: {
            locationPlacementId: 'Internal_2014-09-01',
            quotaId: 'Internal_2014-09-01',
            spendingLimit: 'Off'
          },
          authorizationSource: 'RoleBased'
        },
    */
      console.log(subscriptionDetails);
    }
  } catch (err) {
    console.error(JSON.stringify(err));
  }
}

listSubscriptions()
  .then(() => {
    console.log("done");
  })
  .catch((ex) => {
    console.log(ex);
  });

Asynchronní stránkování výsledků

Metoda SADY SDK může vrátit asynchronní iterátor PagedAsyncIterableIterator, který umožňuje asynchronní výsledky. Výsledky můžou používat stránkovací a pokračovací tokeny k rozdělení sad výsledků.

Následující příklad JavaScriptu ukazuje asynchronní stránkování. Kód nastaví uměle krátkou velikost stránkování 2, aby rychle a vizuálně ukázal proces při spuštění ukázkového kódu v ladění.

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

const blobAccountConnectionString = "REPLACE-WITH-YOUR-STORAGE-CONNECTION-STRING";
const blobAccountContainerName = "REPLACE-WITH-YOUR-STORAGE-CONTAINER-NAME";

const pageSize = 2;

const list = async () => {

  console.log(`List`);

  let continuationToken = "";
  let currentPage = 1;
  let containerClient=null;
  let currentItem = 1;

  // Get Blob Container - need to have items in container before running this code
  const blobServiceClient = BlobServiceClient.fromConnectionString(blobAccountConnectionString);
  containerClient = blobServiceClient.getContainerClient(blobAccountContainerName);

  do {

    // Get Page of Blobs
    iterator = (continuationToken != "") 
      ? containerClient.listBlobsFlat().byPage({ maxPageSize: pageSize, continuationToken }) 
      : containerClient.listBlobsFlat().byPage({ maxPageSize: pageSize });
    
    page = (await iterator.next()).value;

    // Display list
    if (page.segment?.blobItems) {
      console.log(`\tPage [${currentPage}] `);
      for (const blob of page.segment.blobItems) {
        console.log(`\t\tItem [${currentItem++}] ${blob.name}`);
      }
    };

    // Move to next page
    continuationToken = page.continuationToken;
    if (continuationToken) {
      currentPage++;
    }

  } while (continuationToken != "")
}

list(() => {
  console.log("done");
}).catch((ex) =>
  console.log(ex)
);

Další informace o stránkování a iterátorech v Azure:

Dlouhotrvající operace

Metoda sady SDK může vrátit dlouho běžící operaci (LRO). Tato odpověď obsahuje informace, mezi které patří:

  • Vaše žádost byla dokončena.
  • Váš požadavek je stále v procesu.

Následující příklad JavaScriptu ukazuje, jak počkat na dokončení LRO s .pollUntildone(), před pokračováním.

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

const blobAccountConnectionString = "REPLACE-WITH-YOUR-STORAGE-CONNECTION-STRING";
const blobAccountContainerName = `test-${Date.now().toString()}`;

const files = [
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/README.md",
    "fileName": "README.md"
  },
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/gulpfile.ts",
    "fileName": "gulpfile.ts"
  },
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/rush.json",
    "fileName": "rush.json"
  },  
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/package.json",
    "fileName": "package.json"
  },
  {
    "url": "https://github.com/Azure/azure-sdk-for-js/blob/main/tsdoc.json",
    "fileName": "tsdoc.json"
  },
];

const upload = async() => {

  // get container client
  const blobServiceClient = BlobServiceClient.fromConnectionString(blobAccountConnectionString);

  // get container's directory client
  const containerClient = blobServiceClient.getContainerClient(blobAccountContainerName);

  files.forEach(async(file) =>{
    await (

      await containerClient
        .getBlobClient(file.fileName)
        .beginCopyFromURL(file.url)
  
    ).pollUntilDone();
  })
}

upload(() => {
  console.log("done");
}).catch((ex) =>
  console.log(ex)
);

Další informace o dlouhotrvajících operacích v Azure:

Zrušení asynchronních operací

Balíček @azure/abort-controller poskytuje třídy AbortController a AbortSignal. Pomocí AbortController vytvořte AbortSignal, který pak lze předat operacím sady Azure SDK a zrušit čekající práci. Operace sady Azure SDK můžou být:

  • Přerušeno na základě vlastní logiky
  • Přerušeno na základě limitu časového limitu
  • Přerušeno na základě signálu nadřazeného úkolu
  • Přerušeno na základě signálu nadřazeného úkolu nebo limitu časového limitu

Další informace:

Podrobné protokolování ze sady SDK

Při použití sady Azure SDK může docházet k časům, kdy potřebujete ladit aplikaci.

  • Pokud chcete povolit protokolování v době sestavení, nastavte proměnnou prostředí AZURE_LOG_LEVEL na infohodnotu .

  • Pokud chcete povolit protokolování za běhu, použijte balíček @azure/logger:

    import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Svazování

Další informace o sdružování se sadou Azure SDK:

Další kroky