Aracılığıyla paylaş

JavaScript ve TypeScript için Azure istemci kitaplıklarını kullanma

  • Makale

Azure hizmetlerinize program aracılığıyla erişmek için JavaScript için Azure istemci kitaplıklarını kullanın. Genellikle, bu kitaplıkların kapsamı microsoft1estarafından yayımlanan @azure npm paketi kapsamıyla belirlenmiştir.

İstemci kitaplıkları ile REST API'leri arasındaki farklar

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

  • Azure istemci kitaplıkları, Azure hizmetinize erişmek için tercih edilen yöntemdir. Bu kitaplıklar, kimlik doğrulama, yeniden deneme ve günlüğe kaydetme gibi bulut tabanlı Azure platformu REST isteklerini yönetmek için gereken önceden yazılmış kodu soyutlar.
  • Azure REST API'leri aşağıdaki durumlarda tercih edilen yöntemdir:
    • Kullanılabilir Azure istemci kitaplıkları olmayan önizleme hizmetleriyle çalışma. Kodunuzu önizleme olarak düşünün; bu, hizmet istemci kitaplıklarıyla genel kullanıma sunulduğ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 istemci kitaplığı sürümleri şu şekilde kullanılabilir:

  • Yönetim: Yönetim kitaplıkları, Azure kaynaklarını oluşturmanıza ve yönetmenize olanak tanır. Bu kitaplıkları paket adlarında arm- olarak tanımlayabilirsiniz. arm terimi Azure Resource Manager'a işaret eder.
  • İstemci: Bir Azure kaynağı zaten mevcut olduğunda, istemci kitaplıklarını kullanarak bu kaynağı kullanın ve bu kaynakla etkileşim kurun.
    • Her paket README.md belgeler ve örnekler içerir.

Azure npm paketlerini yükleme

Azure istemci kitaplıkları NPM ve Yarn'den ücretsiz olarak kullanılabilir. Gerektiğinde tek tek SDK'ları yükleyin. Her SDK, TypeScript tanımları sağlar.

İstemci/tarayıcı kullanımı için Azure istemci kitaplıkları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 paketin belgelerine bakın.

Kimlik doğrulama bilgilerini sağlayın

Azure istemci kitaplıkları, Azure platformu üzerinde kimlik doğrulamak için kimlik bilgilerigerektirir. Kimlik bilgisi sınıfları tarafından sağlanan @azure/identity çeşitli avantajlar sağlar:

  • Hızlı işe alıştırma
  • 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ğlayın.

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

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

Aşağıdaki kod örneği, bu kimlik bilgisinin okuma erişimi olan abonelikleri listelemek için DefaultAzureCredential ve arm abonelik istemci kitaplığını kullanır.

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ı

SDK yöntemi, asenkron sonuçlara izin vermek için PagedAsyncIterableIteratoradında bir asenkron yineleyici döndürebilir. Sonuçlar, sonuç kümelerini ayırmak için sayfalama ve devam belirteçleri kullanabilir.

Aşağıdaki JavaScript örneği zaman uyumsuz sayfalamayı göstermektedir. 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 sayfalama boyutu 2 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 sayfalandırma 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) veham 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 .pollUntildone()ile LRO'ların 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 kararınız doğrultusunda yarıda kesildi
  • Zaman aşımı sınırına göre sonlandırıldı
  • Üst görevin sinyaline göre iptal edildi
  • Üst görevin sinyal veya zaman aşımı sınırı durduruldu

Daha fazla bilgi edinin:

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

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

  • derleme zamanıgünlüğe kaydetmeyi etkinleştirmek için AZURE_LOG_LEVEL ortam değişkenini infoolarak ayarlayı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