Aracılığıyla paylaş

JavaScript ve TypeScript için Azure SDK'larını kullanma

  • Makale

Azure hizmetlerinize program aracılığıyla erişmek için JavaScript için Azure SDK'larını kullanın. Bu SDK'ların kapsamı genellikle azure-sdk tarafından yayımlanan @azure npm paketi kapsamıyla belirlenmiştir.

SDK'lar ve REST API'ler arasındaki farklar

Hangi tür erişim mekanizmasının ne zaman kullanılacağını anlamak için aşağıdaki bilgileri kullanın.

  • Azure SDK'ları, Azure hizmetinize erişmek için tercih edilen yöntemdir. Azure SDK'ları kimlik doğrulaması, yeniden denemeler ve günlüğe kaydetme gibi bulut tabanlı Azure platformu REST isteklerini yönetmek için gereken ortak kodu soyutlar.
  • Aşağıdaki durumlarda Azure REST API'leri tercih edilen yöntemdir:
    • Kullanılabilir Azure SDK'ları olmayan önizleme hizmetleriyle çalışma. Kodunuzu önizleme olarak düşünün; bu, hizmet genel olarak SDK'larla kullanılabilir olduğunda güncelleştirilmelidir.
    • SDK'nın tamamının tek bir REST API kullanmasını istemediğinizden veya HTTP istekleri üzerinde daha derin denetim sahibi olmasını istediğinizden doğrudan REST çağrıları yapmak istiyorsunuz.

Azure istemci ve yönetim kitaplıkları

Azure SDK sürümleri şu şekilde kullanılabilir:

  • Yönetim SDK'ları: Yönetim kitaplıkları, Azure Resource Manager (ARM) aracılığıyla Azure kaynaklarını sağlamanızı ve yönetmenizi sağlar. Bu kitaplıkları @azure/arm- paket adlarında tanıyabilirsiniz.
  • İstemci SDK'ları: Bir Azure kaynağı zaten mevcut olduğunda, istemci kitaplıklarını kullanarak onu kullanabilir ve bu kaynakla etkileşim kurabilirsiniz.
    • Her paket README.md belgeler ve örnekler içerir.

Azure npm paketlerini yükleme

Azure SDK'ları NPM'den ücretsiz olarak kullanılabilir. Gereken tek tek SDK'ları yükleyin. Her SDK, TypeScript tanımları sağlar.

İstemci/tarayıcı kullanımı için Azure SDK'larının paketleme işleminize eklenmesi gerekir.

Azure npm paket örnek kodunu kullanma

Her pakette, paketi hızlı bir şekilde kullanmaya başlamanıza yardımcı olacak belgeler bulunur. Bunları kullanmayı öğrenmek için kullandığınız belirli NPM paketlerine bakın.

Kimlik doğrulaması kimlik bilgilerini sağlama

Azure SDK'ları, Azure platformunda kimlik doğrulaması yapmak için kimlik bilgileri gerektirir. @azure/kimlik tarafından sağlanan kimlik bilgisi sınıfları çeşitli avantajlar sağlar:

  • Hızlı ekleme
  • En güvenli yöntem
  • Kimlik doğrulama mekanizmasını koddan ayırın. Bu, kimlik bilgileri farklıyken aynı kodu yerel olarak ve Azure platformunda kullanmanıza olanak tanır.
  • Çeşitli mekanizmaların kullanılabilmesi için zincirlenmiş kimlik doğrulaması sağlama

SDK istemcisi oluşturma ve yöntemleri çağırma

Program aracılığıyla bir kimlik bilgisi oluşturduktan sonra, kimlik bilgilerini Azure SDK'nızın istemcisine geçirin. İstemci, abonelik kimliği veya hizmet URL'si gibi ek bilgiler gerektirebilir. Bu değerler, kaynağınız için Azure portalında kullanılabilir.

Bu kimlik bilgilerinin okuma erişimi olan abonelikleri listeleyin.

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

Sonuçların zaman uyumsuz sayfalaması

BIR SDK yöntemi, zaman uyumsuz sonuçlara izin vermek için zaman uyumsuz bir yineleyici ( PagedAsyncIterableIterator) döndürebilir. Sonuçlar, sonuç kümelerini ayırmak için disk belleği ve devamlılık belirteçleri kullanabilir.

Aşağıdaki JavaScript örneğinde zaman uyumsuz disk belleği gösterilmektedir. Kod, hata ayıklamada örnek kodu çalıştırdığınızda işlemi hızlı ve görsel olarak göstermek için yapay olarak kısa bir disk belleği boyutu 2'yi ayarlar.

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

Azure'da disk belleği ve yineleyiciler hakkında daha fazla bilgi edinin:

Uzun süre çalışan işlemler

SDK yöntemi uzun süre çalışan bir işlem (LRO) ham yanıtı döndürebilir. Bu yanıt aşağıdakileri içeren bilgileri içerir:

  • İsteğiniz tamamlandı
  • İsteğiniz hala devam ediyor

Aşağıdaki JavaScript örneği , devam etmeden önce LRO'ların ile .pollUntildone()tamamlanmasını nasıl bekleyeceğinizi gösterir.

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

Azure'da uzun süre çalışan işlemler hakkında daha fazla bilgi edinin:

Zaman uyumsuz işlemleri iptal etme

@azure/abort-controller paketi AbortController ve AbortSignal sınıfları sağlar. AbortController'ı kullanarak AbortSignal oluşturun. Bu işlem, bekleyen çalışmayı iptal etmek için Azure SDK işlemlerine geçirilebilir. Azure SDK işlemleri şu şekilde olabilir:

  • Kendi mantığınıza göre durduruldu
  • Zaman aşımı sınırına göre durduruldu
  • Üst görevin sinyaline göre durduruldu
  • Üst görevin sinyaline veya zaman aşımı sınırına göre durduruldu

Daha fazla bilgi edinin:

SDK'dan ayrıntılı günlük kaydı

Azure SDK kullanırken, uygulamanızda hata ayıklamanız gereken zamanlar olabilir.

  • Derleme zamanında günlüğe kaydetmeyi etkinleştirmek için AZURE_LOG_LEVEL ortam değişkenini olarak infoayarlayın.

  • Çalışma zamanında günlüğe kaydetmeyi etkinleştirmek için @azure/günlükçü paketini kullanın:

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

setLogLevel("info");

Paketleme

Azure SDK ile paketleme hakkında bilgi edinin:

Sonraki adımlar