Korzystanie z zestawów SDK platformy Azure dla języków JavaScript i TypeScript

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

Różnice między zestawami SDK i interfejsami API REST

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

• Zestawy SDK platformy Azure to preferowana metoda uzyskiwania dostępu do usługi platformy Azure. Zestawy SDK platformy Azure 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 zestawów SDK platformy Azure. Weź pod uwagę kod jako podgląd, który powinien zostać zaktualizowany, gdy usługa jest ogólnie dostępna za pomocą zestawów SDK.
  • 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 zestawu Azure SDK są dostępne jako:

• Zestawy SDK zarządzania: biblioteki zarządzania umożliwiają aprowizację zasobów platformy Azure i zarządzanie nimi za pośrednictwem usługi Azure Resource Manager (ARM). Te biblioteki @azure/arm- można rozpoznać w nazwach pakietów.
  • Dokumentacja i przykłady kodu
• Zestawy SDK klienta: biorąc pod uwagę, że zasób platformy Azure już istnieje, należy użyć 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

Zestawy SDK platformy Azure są bezpłatnie dostępne w usłudze NPM. Zainstaluj wymagane poszczególne zestawy SDK. Każdy zestaw SDK zawiera definicje języka TypeScript.

W przypadku użycia klienta/przeglądarki zestawy SDK 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

Zestawy SDK 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.
• Zapewnianie uwierzytelniania łańcuchowego, dzięki czemu można 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 zestawu Azure SDK. Klient może wymagać dodatkowych informacji, takich jak identyfikator subskrypcji lub adres URL usługi. Te wartości są dostępne w witrynie Azure Portal dla zasobu.

Wyświetl listę subskrypcji, do których ma dostęp ten poświadczenie 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:

• Asynchroniczne iteratory w zestawie Azure SDK dla języka JavaScript/TypeScript

Długotrwałe operacje

Metoda zestawu SDK może zwrócić odpowiedź na długotrwałą operację (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:

• @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 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:

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

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:

• Aby połączyć zestawy SDK platformy Azure
• Próbki grupowania

Następne kroki

• Wyświetlanie listy subskrypcji przy użyciu zestawu SDK @azure/arm-subscriptions
• Wyświetlanie listy ostatnich operacji zasobów za pomocą zestawu SDK @azure/arm-monitora
• Tworzenie maszyny wirtualnej przy użyciu zestawu SDK @azure/arm-compute