Menggunakan SDK Azure untuk JavaScript dan TypeScript

  • Artikel

Untuk mengakses layanan Azure Anda secara terprogram, gunakan SDK Azure untuk JavaScript. Biasanya, SDK ini dicakup dengan cakupan paket npm @azure yang diterbitkan oleh azure-sdk.

Perbedaan antara SDK dan REST API

Gunakan informasi berikut untuk memahami kapan harus menggunakan jenis mekanisme akses mana.

  • SDK Azure adalah metode yang disukai untuk mengakses layanan Azure Anda. SDK Azure mengabstraksi kode boilerplate yang diperlukan untuk mengelola permintaan REST platform Azure berbasis-cloud seperti autentikasi, coba ulang, dan pencatatan.
  • AZURE REST API adalah metode yang lebih disukai jika Anda:
    • Bekerja dengan layanan pratinjau yang tidak memiliki SDK Azure yang tersedia. Menganggap kode Anda sebagai pratinjau, yang harus diperbarui saat layanan umumnya tersedia dengan SDK.
    • Ingin melakukan panggilan REST secara langsung karena Anda tidak ingin seluruh SDK menggunakan satu REST API atau Anda menghendaki kontrol yang lebih dalam atas permintaan HTTP.

Pustaka klien dan manajemen Azure

Rilis Azure SDK tersedia sebagai:

  • SDK Manajemen: Pustaka manajemen memungkinkan Anda untuk menyediakan dan mengelola sumber daya Azure melalui Azure Resource Manager (ARM). Anda dapat mengenali pustaka ini dengan @azure/arm- pada nama paket mereka.
  • SDK Klien: Mengingat sumber daya Azure sudah ada, Anda akan menggunakan pustaka klien untuk mengonsumsi dan berinteraksi dengannya.
    • Setiap paket README.md mencakup dokumentasi dan sampel.

Instal paket Azure npm

SDK Azure tersedia secara bebas dari NPM. Instal SDK individual yang diperlukan. Setiap SDK menyediakan definisi TypeScript.

Untuk penggunaan klien/browser, SDK Azure perlu ditambahkan ke proses bundling Anda.

Menggunakan kode sampel paket Azure npm

Setiap paket menyertakan dokumentasi agar Anda bisa memulai paket dengan cepat. Lihat paket NPM tertentu yang Anda gunakan untuk mempelajari cara menggunakannya.

Berikan kredensial autentikasi

SDK Azure memerlukan kredensial untuk mengautentikasi ke platform Azure. Kelas kredensial yang disediakan oleh @azure /identitas memberikan beberapa manfaat:

  • Onboarding cepat
  • Metode paling aman
  • Memisahkan mekanisme autentikasi dari kode. Kredensial ini memungkinkan Anda untuk menggunakan kode yang sama secara lokal dan di platform Azure meskipun kredensialnya berbeda.
  • Menyediakan autentikasi berantai sehingga beberapa mekanisme dapat tersedia

Membuat klien SDK dan metode panggilan

Setelah Anda membuat kredensial secara terprogram, berikan kredensial ke klien Azure SDK Anda. Klien mungkin memerlukan informasi tambahan seperti ID langganan atau URL layanan. Nilai-nilai ini tersedia di portal Microsoft Azure, untuk sumber daya Anda.

Daftar langganan yang dapat dibaca oleh kredensial ini.

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

Paging asinkron hasil

Metode SDK dapat mengembalikan iterator asinkron, PagedAsyncIterableIterator, untuk memungkinkan hasil asinkron. Hasilnya dapat menggunakan token per halaman dan kontinyu untuk memecah set hasil.

Contoh JavaScript berikut menunjukkan paging asinkron. Kode ini menetapkan ukuran paging artifisial pendek 2 agar secara cepat dan visual menunjukkan proses itu ketika Anda menjalankan kode sampel dalam debug.

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

Pelajari lebih lanjut tentang paging dan iterator di Azure:

Operasi jangka panjang

Metode SDK dapat mengembalikan respons operasi jangka panjang (LRO). Respon ini mencakup informasi yang meliputi:

  • Permintaan Anda yang selesai
  • Permintaan Anda yang masih dalam proses

Contoh JavaScript berikut menunjukkan cara menunggu LRO selesai, dengan .pollUntildone(), sebelum melanjutkan.

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

Pelajari lebih lanjut tentang operasi yang berjalan lama di Azure:

Membatalkan operasi asinkron

Paket @azure/abort-controller menyediakan kelas AbortController dan AbortSignal. Gunakan AbortController untuk membuat AbortSignal, yang kemudian dapat diteruskan ke operasi Azure SDK untuk membatalkan pekerjaan yang tertunda. Operasi Azure SDK dapat:

  • Dibatalkan berdasarkan logika Anda sendiri
  • Dibatalkan berdasarkan batas waktu selesai
  • Dibatalkan berdasarkan sinyal tugas orang tua
  • Dibatalkan berdasarkan sinyal tugas induk atau batas waktu selesai

Pelajari lebih lanjut:

Pengelogan verbose dari SDK

Saat menggunakan Azure SDK, mungkin ada saat-saat ketika Anda perlu men-debug aplikasi Anda.

  • Untuk mengaktifkan pencatatan pada build-time, atur variabel lingkungan AZURE_LOG_LEVEL ke info.

  • Untuk mengaktifkan pencatatan pada run-time, gunakan paket @azure/logger :

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

setLogLevel("info");

Bundling

Pelajari tentang bundling dengan Azure SDK:

Langkah berikutnya