Udostępnij za pośrednictwem

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

  • Artykuł

Aby programowo uzyskać dostęp do usług platformy Azure, użyj bibliotek klienckich platformy Azure dla języka JavaScript. Zazwyczaj te biblioteki są ograniczone do zakresu @azure zakresu pakietów npm opublikowanego przez zestaw azure-sdk.

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 klienckie 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

Wersje biblioteki klienta platformy Azure są dostępne jako:

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

Instalowanie pakietów npm platformy Azure

Biblioteki klienckie platformy Azure są bezpłatnie dostępne w programie NPM. 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 konkretnymi pakietami NPM, których używasz, aby dowiedzieć się, jak z nich korzystać.

Podawanie poświadczeń uwierzytelniania

Biblioteki klienta platformy Azure wymagają poświadczeń w celu uwierzytelnienia na platformie Azure. Klasy poświadczeń udostępniane przez @azure/tożsamość zapewniają kilka korzyści:

  • Szybkie dołączanie
  • 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 witrynie Azure Portal dla zasobu.

W poniższym przykładzie kodu użyto biblioteki klienta DefaultAzureCredential i arm biblioteki klienta subskrypcji, 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 zestawu SDK może zwracać iterator asynchroniczny PagedAsyncIterableIterator, aby zezwolić na wyniki asynchroniczne. Wyniki mogą używać tokenów stronicowania i kontynuacji do dzielenia zestawów wyników.

W poniższym przykładzie języka JavaScript pokazano 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:

Długotrwałe operacje

Metoda zestawu SDK może zwrócić odpowiedź nieprzetworzonej długotrwałej operacji (LRO). Ta odpowiedź zawiera informacje, w tym:

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

W poniższym przykładzie języka JavaScript pokazano, jak poczekać na ukończenie procesu LRO z wartością .pollUntildone(), zanim przejdziesz dalej.

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:

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 zestawu Azure SDK, aby anulować oczekujące prace. Operacje zestawu Azure SDK mogą być następujące:

  • Przerwane na podstawie własnej logiki
  • Przerwane na podstawie limitu czasu
  • Przerwane na podstawie sygnału zadania nadrzędnego
  • Przerwane na podstawie sygnału zadania nadrzędnego lub limitu czasu

Więcej informacji:

Pełne rejestrowanie z zestawu SDK

W przypadku korzystania z zestawu Azure SDK mogą wystąpić czasy, kiedy trzeba debugować aplikację.

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

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

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

setLogLevel("info");

Łączenie

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

Następne kroki