Używanie bibliotek klienckich platformy Azure dla języków JavaScript i TypeScript

Aby programowo uzyskać dostęp do usług platformy Azure, użyj bibliotek klienckich platformy Azure dla języka JavaScript. Zazwyczaj te biblioteki mają zakres pakietu npm @azure opublikowany przez microsoft1es.

Różnice między bibliotekami klienckimi i interfejsami API REST

Skorzystaj z poniższych informacji, aby dowiedzieć się, kiedy używać typu dostępu.

• Biblioteki klienta platformy Azure są preferowaną metodą uzyskiwania dostępu do usługi platformy Azure. Te biblioteki oddzielają standardowy kod wymagany do zarządzania żądaniami REST platformy Azure opartymi na chmurze, takimi jak uwierzytelnianie, ponawianie prób i rejestrowanie.
• Interfejsy API REST platformy Azure są preferowaną metodą, jeśli:
  • Praca z usługami w wersji zapoznawczej, które nie mają dostępnych bibliotek klienckich platformy Azure. Rozważ użycie kodu jako wersji zapoznawczej, który powinien zostać zaktualizowany, gdy usługa jest ogólnie dostępna w bibliotekach klienckich.
  • Chcesz wykonywać wywołania REST bezpośrednio, ponieważ nie chcesz, aby cały zestaw SDK używał pojedynczego interfejsu API REST lub chcesz mieć głębszą kontrolę nad żądaniami HTTP.

Biblioteki klienta i zarządzania platformy Azure

Biblioteka klienta Azure wydania są dostępne jako:

• Management: biblioteki zarządzania umożliwiają tworzenie zasobów platformy Azure i zarządzanie nimi. Te biblioteki można rozpoznać po arm- w nazwach pakietów. Termin arm wskazuje usługę Azure Resource Manager.
  • dokumentacja i przykłady kodu
• klienta: biorąc pod uwagę, że zasób platformy Azure już istnieje, użyj bibliotek klienckich do korzystania z niego i interakcji z nim.
  • README.md każdego pakietu zawiera dokumentację i przykłady.

Instalowanie pakietów npm platformy Azure

Biblioteki klienckie platformy Azure są dostępne za darmo w NPM i Yarn. Zainstaluj poszczególne zestawy SDK zgodnie z potrzebami. Każdy zestaw SDK zawiera definicje języka TypeScript.

W przypadku użycia klienta/przeglądarki biblioteki klienckie platformy Azure należy dodać do procesu tworzenia pakietów.

Korzystanie z przykładowego kodu pakietu npm platformy Azure

Każdy pakiet zawiera dokumentację, aby szybko rozpocząć pracę z pakietem. Zapoznaj się z dokumentacją określonego pakietu, której używasz, aby dowiedzieć się, jak z nich korzystać.

Podawanie poświadczeń uwierzytelniania

Biblioteki klienta platformy Azure wymagają poświadczeń do uwierzytelniania na platformie Azure. klasy poświadczeń udostępniane przez @azure/identity zapewniają kilka korzyści:

• Szybkie wprowadzenie
• Najbezpieczniejsza metoda
• Oddziel mechanizm uwierzytelniania od kodu. Dzięki temu można używać tego samego kodu lokalnie i na platformie Azure, gdy poświadczenia są inne.
• Zapewnij uwierzytelnianie łańcuchowe, aby można było uzyskać dostęp do kilku mechanizmów.

Tworzenie klienta zestawu SDK i metod wywoływania

Po programowym utworzeniu poświadczeń przekaż poświadczenie do klienta platformy Azure. Klient może wymagać dodatkowych informacji, takich jak identyfikator subskrypcji lub punkt końcowy usługi. Te wartości są dostępne w portalu Azure dla Twojego zasobu.

W poniższym przykładzie kodu użyto DefaultAzureCredential oraz biblioteki klienta subskrypcji arm, aby wyświetlić listę subskrypcji, do których to poświadczenie ma dostęp do odczytu.

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);
  });

Asynchroniczne stronicowanie wyników

Metoda SDK może zwrócić asynchroniczny iterator, PagedAsyncIterableIterator, umożliwiając uzyskiwanie wyników asynchronicznych. Wyniki mogą używać tokenów stronicowania i kontynuacji do dzielenia zestawów wyników.

Poniższy przykład JavaScript ilustruje asynchroniczne stronicowanie. Kod ustawia sztucznie krótki rozmiar stronicowania 2, aby szybko i wizualnie zademonstrować proces podczas uruchamiania przykładowego kodu w debugowaniu.

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)
);

Dowiedz się więcej o stronicowaniu i iteratorach na platformie Azure:

• Iteratory Asynchroniczne w Zestawie Azure SDK dla Języka JavaScript/TypeScript

Długotrwałe operacje

Metoda SDK może zwrócić operację długotrwałą (LRO) w formie surowej odpowiedzi. Ta odpowiedź zawiera informacje, w tym:

• Żądanie zostało ukończone
• Twoje żądanie jest nadal w toku

Poniższy przykład JavaScript pokazuje, w jaki sposób poczekać na ukończenie LRO z .pollUntildone(), zanim kontynuujemy.

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)
);

Dowiedz się więcej o długotrwałych operacjach na platformie Azure:

• @azure/core-lro

Anulowanie operacji asynchronicznych

Pakiet @azure/abort-controller udostępnia klasy AbortController i AbortSignal. Użyj AbortController, aby utworzyć AbortSignal, który następnie można przekazać do operacji w Azure SDK, aby anulować oczekujące zadania. Operacje zestawu Azure SDK mogą być następujące:

• Przerwane na podstawie twojej własnej logiki
• Przerwane z powodu limitu czasu
• Przerwane na podstawie sygnału zadania nadrzędnego
• Przerwane z powodu sygnału zadania nadrzędnego lub, albo z powodu limitu czasu.

Dowiedz się więcej:

• Jak używać sygnałów przerwania do anulowania operacji w zestawie Azure SDK dla języka JavaScript/TypeScript

Szczegółowe rejestrowanie z zestawu SDK

W przypadku korzystania z zestawu Azure SDK mogą wystąpić czasy, w których trzeba debugować aplikację.

• Aby włączyć rejestrowanie w czasie kompilacji, ustaw zmienną środowiskową AZURE_LOG_LEVEL na info.

• Aby włączyć rejestrowanie w czasu wykonywania, użyj pakietu / @azure/rejestratora:

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

Pakietowanie

Dowiedz się więcej o tworzeniu pakietów za pomocą zestawu Azure SDK:

• Aby powiązać zestawy SDK platformy Azure
• Przykłady pakietu

Następne kroki

• Wyświetl listę subskrypcji za pomocą zestawu @azure/arm-subscriptions SDK
• Wyświetl ostatnie operacje zasobów przy użyciu SDK @azure/arm-monitor