Použití klientských knihoven Azure pro JavaScript a TypeScript

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

Rozdíly mezi klientskými knihovnami a rozhraními REST API

Následující informace vám porozumí, kdy použít typ přístupu.

• Upřednostňovaným způsobem přístupu ke službě Azure jsou klientské knihovny Azure,. Tyto knihovny abstrahují č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í.
• rozhraní Azure REST API jsou upřednostňovanou metodou, pokud jste:
  • Práce se službami ve verzi Preview, které nemají k dispozici klientské knihovny Azure Vezměte v úvahu váš kód jako verzi Preview, která by se měla aktualizovat, když je služba obecně dostupná v klientských knihovnách.
  • 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

Jsou k dispozici následující verze klientské knihovny Azure :

• Management: Knihovny pro správu umožňují vytvářet a spravovat prostředky Azure. Tyto knihovny můžete rozpoznat podle arm- v jejich názvech balíčků. Termín arm označuje Azure Resource Manager.
  • dokumentaci a ukázky kódu
• Klient: Vzhledem k tomu, že prostředek Azure již existuje, použijte klientské knihovny k jeho spotřebě a interakci s ním.
  • Každý balíček README.md zahrnuje dokumentaci a ukázky.

Instalace balíčků Azure npm

Klientské knihovny Azure jsou volně dostupné z NPM aYarn . Podle potřeby nainstalujte jednotlivé sady SDK. 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 klientské knihovny 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 dokumentaci ke konkrétnímu balíčku.

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

Klientské knihovny Azure vyžadují přihlašovací údaje k ověření na platformě Azure. třídy pověření poskytované @azure/identity poskytují několik výhod:

• Rychlé zaškolení
• 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ší.
• Poskytovat řetězení ověřování, aby bylo několik mechanismů dostupných.

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 Azure. Klient může vyžadovat další informace, jako je ID předplatného nebo koncový bod služby. Tyto hodnoty jsou k dispozici na webu Azure Portal pro váš prostředek.

Následující příklad kódu používá DefaultAzureCredential a klientskou knihovnu arm předplatného k výpisu 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 SDK může vrátit asynchronní iterátor PagedAsyncIterableIterator, pro umožnění asynchronních výsledků. 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í velikost stránkování uměle malou, hodnotu 2, aby rychle a vizuálně předvedl 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 iteračním cyklu na Azure:

• Asynchronní iterátory v sadě Azure SDK pro JavaScript/TypeScript

Dlouhotrvající operace

Metoda SDK může vrátit dlouhotrvající operaci (LRO) nebo surovou odpověď. 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(), než budete pokračovat.

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:

• @azure/core-lro

Zrušení asynchronních operací

Balíček kontroleru @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ě časového limitu
• Přerušeno na základě signálu nadřazeného úkolu
• Přerušeno na základě signálu přidruženého úkolu nebo časového limitu

Víc se uč:

• Použití přerušených signálů ke zrušení operací v sadě Azure SDK pro JavaScript nebo TypeScript

Podrobné protokolování ze sady SDK

Když používáte sadu Azure SDK, může docházet k časům, kdy potřebujete ladit aplikaci.

• Pokud chcete povolit protokolování při sestavení, nastavte proměnnou prostředí AZURE_LOG_LEVEL na info.

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

  import { setLogLevel } from "@azure/logger";
  
  setLogLevel("info");
  

Svazkování

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

• Seskupit sady SDK Azure
• Ukázky balíčkování

Další kroky

• Výpis předplatných s @azure/arm-subscriptions SDK
• Výpis nedávných operací prostředků pomocí sady @azure/arm-monitor SDK