موفر تكوين JavaScript

Azure App Configuration هي خدمة مدارة تساعد المطورين على مركزية تكوينات التطبيقات الخاصة بهم ببساطة وأمان. تتيح مكتبة موفر تكوين JavaScript تحميل التكوين من مخزن Azure App Configuration بطريقة مدارة. تضيف مكتبة العميل هذه وظائف إضافية أعلى Azure SDK ل JavaScript.

تحميل التكوين

load يتم استخدام الأسلوب المصدر في الحزمة @azure/app-configuration-provider لتحميل التكوين من Azure App Configuration. load يسمح لك الأسلوب إما باستخدام معرف Microsoft Entra أو سلسلة الاتصال للاتصال بمخزن App Configuration.

معرِّف Microsoft Entra
سلسلة الاتصال

يمكنك استخدام DefaultAzureCredential للمصادقة على متجر App Configuration. اتبع الإرشادات لتعيين بيانات الاعتماد الخاصة بك دور قارئ بيانات تكوين التطبيق.

const { load } = require("@azure/app-configuration-provider");
const { DefaultAzureCredential } = require("@azure/identity");
const endpoint = process.env.AZURE_APPCONFIG_ENDPOINT;
const credential = new DefaultAzureCredential(); // For more information, see https://learn.microsoft.com/azure/developer/javascript/sdk/credential-chains#use-defaultazurecredential-for-flexibility

async function run() {
    // Connect to Azure App Configuration using a token credential and load all key-values with no label.
    const appConfig = await load(endpoint, credential);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

const { load } = require("@azure/app-configuration-provider");
const connectionString = process.env.AZURE_APPCONFIG_CONNECTION_STRING;

async function run() {
    // Connect to Azure App Configuration using a connection string and load all key-values with no label.
    const appConfig = await load(connectionString);
    console.log('appConfig.get("message"):', appConfig.get("message"));
}

run();

يقوم load الأسلوب بإرجاع مثيل من AzureAppConfiguration النوع الذي يتم تعريفه على النحو التالي:

type AzureAppConfiguration = {
    refresh(): Promise<void>;
    onRefresh(listener: () => any, thisArg?: any): Disposable;
} & IGettable & ReadonlyMap<string, any> & IConfigurationObject;

لمزيد من المعلومات حول refresh وأساليب، onRefresh راجع قسم تحديث التكوين.

استهلاك التكوين

يوسع AzureAppConfiguration النوع الواجهات التالية:

IGettable

interface IGettable {
    get<T>(key: string): T | undefined;
}

توفر IGettable الواجهة get طريقة لاسترداد قيمة قيمة مفتاح من بنية البيانات على غرار الخريطة.

const appConfig = await load(endpoint, credential);
const fontSize = appConfig.get("app:font:size"); // value of the key "app:font:size" from the App Configuration store

ReadonlyMap

يقوم AzureAppConfiguration النوع أيضا بتوسيع الواجهة ReadonlyMap ، ما يوفر وصولا للقراءة فقط إلى أزواج قيم المفاتيح.
IConfigurationObject
```
interface IConfigurationObject {
    constructConfigurationObject(options?: ConfigurationObjectConstructionOptions): Record<string, any>;
}
```
توفر IConfigurationObject الواجهة constructConfigurationObject أسلوبا لإنشاء كائن تكوين استنادا إلى بنية بيانات على غرار الخريطة ومفاتيح هرمية. يمكن استخدام المعلمة الاختيارية ConfigurationObjectConstructionOptions لتحديد الفاصل لتحويل المفاتيح الهرمية إلى خصائص العنصر. بشكل افتراضي، يكون الفاصل هو ".".
```
interface ConfigurationObjectConstructionOptions {
    separator?: "." | "," | ";" | "-" | "_" | "__" | "/" | ":"; // supported separators
}
```
في JavaScript، يتم استخدام الكائنات أو الخرائط بشكل شائع كهياكل بيانات أساسية لتمثيل التكوينات. تدعم مكتبة موفر تكوين JavaScript كلا من نهج التكوين، ما يوفر للمطورين المرونة لاختيار الخيار الذي يناسب احتياجاتهم بشكل أفضل.
```
const appConfig = await load(endpoint, credential);
const settingsObj = appConfig.constructConfigurationObject({separator: ":"});
const fontSize1 = appConfig.get("app:font:size"); // map-style configuration representation
const fontSize2 = settingsObj.app.font.size; // object-style configuration representation
```

معالجة نوع محتوى JSON

يمكنك إنشاء قيم مفاتيح JSON في تكوين التطبيق. عند تحميل قيم المفاتيح من Azure App Configuration، سيقوم موفر التكوين تلقائيا بتحويل قيم المفاتيح لنوع محتوى JSON صالح (على سبيل المثال application/json) إلى كائن.

{
    "key": "font",
    "label": null,
    "value": "{\r\n\t\"size\": 12,\r\n\t\"color\": \"red\"\r\n}",
    "content_type": "application/json"
}

سيتم تحميل قيمة المفتاح أعلاه ك { size: 12, color: "red" }.

const appConfig = await load(endpoint, credential);
const { size, color } = appConfig.get("font");

إشعار

بدءا من الإصدار 2.2.0 من @azure/app-configuration-provider، يسمح موفر التكوين بالتعليقات ، كما هو محدد في (JSONC) ، في قيم المفاتيح مع application/json نوع المحتوى.

تحميل قيم مفاتيح محددة باستخدام المحددات

بشكل افتراضي، load سيقوم الأسلوب بتحميل جميع التكوينات بدون تسمية من مخزن التكوين. يمكنك تكوين سلوك الأسلوب من load خلال المعلمة الاختيارية من AzureAppConfigurationOptions النوع.

لتحسين أو توسيع التكوينات المحملة من متجر App Configuration، يمكنك تحديد محددات المفتاح أو التسمية ضمن الخاصية AzureAppConfigurationOptions.selectors .

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys starting with "app1." prefix and "test" label
            keyFilter: "app1.*",
            labelFilter: "test"
        },
        { // load the subset of keys with "dev" label"
            keyFilter: "*",
            labelFilter: "dev"
        }
    ]
});

إشعار

يتم تحميل قيم المفاتيح بالترتيب الذي يتم به سرد المحددات. إذا استرد محددون متعددون قيم المفاتيح بنفس المفتاح، فستتجاوز القيمة من آخر قيمة تم تحميلها مسبقا.

عوامل تصفية العلامات

تحدد معلمة عوامل تصفية العلامات قيم المفاتيح بعلامات محددة. يتم تحميل قيمة المفتاح فقط إذا كانت تحتوي على جميع العلامات والقيم المقابلة المحددة في عوامل التصفية.

const appConfig = await load(endpoint, credential, {
    selectors: [
        { // load the subset of keys with "test" label" and three tags
            keyFilter: "*",
            labelFilter: "test",
            tagFilters: [
                "emptyTag=",
                "nullTag=\0",
                "tag1=value1"
            ]
        }
    ]
});

إشعار

محجوزة العلامة النجمية (*)، الفاصلة (,)، وسلة مائلة عكسية (\) ويجب تخطيها بسلة مائلة عكسية عند استخدامها في عامل تصفية العلامة.

اقتطاع البادئة من المفاتيح

يمكنك اقتطاع البادئة من المفاتيح عن طريق توفير قائمة ببادئات المفاتيح المقتطعة إلى الخاصية AzureAppConfigurationOptions.trimKeyPrefixes .

const appConfig = await load(endpoint, credential, {
    selectors: [{
        keyFilter: "app.*"
    }],
    trimKeyPrefixes: ["app."]
});

تحديث التكوين

يتيح لك التحديث الديناميكي للتكوينات سحب أحدث قيمها من متجر App Configuration دون الحاجة إلى إعادة تشغيل التطبيق. يمكنك تعيين AzureAppConfigurationOptions.refreshOptions لتمكين خيارات التحديث والتكوين. سيتم تحديث التكوين المحمل عند الكشف عن أي تغيير في قيم المفاتيح المحددة على الخادم. بشكل افتراضي، يتم استخدام فاصل تحديث مدته 30 ثانية، ولكن يمكنك تجاوزه باستخدام الخاصية refreshIntervalInMs .

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        refreshIntervalInMs: 15_000
    }
});

لن يؤدي الإعداد refreshOptions وحده إلى تحديث التكوين تلقائيا. تحتاج إلى استدعاء الأسلوب على refreshAzureAppConfiguration المثيل الذي تم إرجاعه بواسطة load الأسلوب لتشغيل تحديث.

// this call is not blocking, the configuration will be updated asynchronously
appConfig.refresh();

يمنع هذا التصميم الطلبات غير الضرورية إلى App Configuration عندما يكون تطبيقك الخاما. يجب تضمين refresh الاستدعاء حيث يحدث نشاط التطبيق الخاص بك. يعرف هذا باسم تحديث التكوين المستند إلى النشاط. على سبيل المثال، يمكنك الاتصال refresh عند معالجة طلب وارد أو داخل تكرار حيث تقوم بتنفيذ مهمة معقدة.

const server = express();
// Use an express middleware to refresh configuration whenever a request comes in
server.use((req, res, next) => {
    appConfig.refresh();
    next();
})

حتى إذا فشل استدعاء التحديث لأي سبب من الأسباب، فسيستمر تطبيقك في استخدام التكوين المخزن مؤقتا. سيتم إجراء محاولة أخرى عند مرور الفاصل الزمني للتحديث الذي تم تكوينه وتشغيل استدعاء التحديث بواسطة نشاط التطبيق الخاص بك. الاستدعاء refresh ليس عملية قبل انقضاء الفاصل الزمني للتحديث المكون، لذلك يكون تأثير الأداء الخاص به ضئيلا حتى إذا تم استدعاؤه بشكل متكرر.

تحديث مخصص لرد الاتصال

onRefresh يتيح لك الأسلوب وظائف رد الاتصال المخصصة التي سيتم استدعاؤها في كل مرة يتم فيها تحديث التكوين المحلي بنجاح مع تغييرات من مخزن Azure App Configuration. يقوم بإرجاع كائن يمكن التخلص منه، والذي يمكنك استخدامه لإزالة رد الاتصال المسجل

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true
    }
});
const disposer = appConfig.onRefresh(() => {
    console.log("Config refreshed.");
});

appConfig.refresh();
// Once the refresh is successful, the callback function you registered will be executed.
// In this example, the message "Config refreshed" will be printed.

disposer.dispose();

التحديث على مفتاح sentinel

مفتاح sentinel هو مفتاح تقوم بتحديثه بعد إكمال تغيير جميع المفاتيح الأخرى. سيراقب موفر التكوين مفتاح sentinel بدلا من جميع قيم المفاتيح المحددة. عند الكشف عن تغيير، يقوم تطبيقك بتحديث كافة قيم التكوين.

const appConfig = await load(endpoint, credential, {
    refreshOptions: {
        enabled: true,
        watchedSettings: [
            { key: "sentinel" }
        ]
    }
});

لمزيد من المعلومات حول تحديث التكوين، انتقل إلى استخدام التكوين الديناميكي في JavaScript.

علامة الميزة

يمكنك إنشاء علامات الميزات في Azure App Configuration. بشكل افتراضي، لن يتم تحميل علامات الميزة بواسطة موفر التكوين. يمكنك تمكين تحميل وتحديث علامات الميزات من خلال AzureAppConfigurationOptions.featureFlagOptions الخاصية عند استدعاء load الأسلوب .

const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        selectors: [ { keyFilter: "*", labelFilter: "Prod" } ],
        refresh: {
            enabled: true, // enable refreshing feature flags
            refreshIntervalInMs: 60_000
        }
    }
});

إشعار

إذا featureFlagOptions تم تمكينه ولم يتم تحديد محدد، فسيحمل موفر التكوين جميع علامات الميزات بدون تسمية من متجر App Configuration.

هام

لاستهلاك علامات الميزات المحملة من Azure App Configuration وإدارتها بشكل فعال، قم بتثبيت الحزمة واستخدامها @microsoft/feature-management . توفر هذه المكتبة طريقة منظمة للتحكم في سلوك الميزة في التطبيق الخاص بك.

إدارة الميزات

توفر مكتبة إدارة الميزات طريقة لتطوير وظائف التطبيق وعرضها استنادا إلى علامات الميزات. تم تصميم مكتبة إدارة الميزات للعمل جنبا إلى جنب مع مكتبة موفر التكوين. سيقوم موفر التكوين بتحميل جميع علامات الميزات المحددة في التكوين ضمن feature_flags قائمة feature_management القسم. ستستهلك مكتبة إدارة الميزات علامات الميزات المحملة لتطبيقك وتديرها.

يوضح المثال التالي كيفية دمج @microsoft/feature-management المكتبة مع موفر التكوين للتحكم ديناميكيا في إمكانية الوصول إلى واجهة برمجة التطبيقات في تطبيق Express استنادا إلى حالة علامة الميزة Beta .

// Load feature flags from Azure App Configuration
import { load } from "@azure/app-configuration-provider";
const appConfig = await load(endpoint, credential, {
    featureFlagOptions: {
        enabled: true, // enable loading feature flags
        refresh: {
            enabled: true // enable refreshing feature flags
        }
    }
});

import { ConfigurationMapFeatureFlagProvider, FeatureManager } from "@microsoft/feature-management";
// Create a feature flag provider which uses the configuration provider as feature flag source
const ffProvider = new ConfigurationMapFeatureFlagProvider(appConfig);
// Create a feature manager which will evaluate the feature flag
const fm = new FeatureManager(ffProvider);

import express from "express";
const server = express();

// Use a middleware to achieve request-driven configuration refresh
server.use((req, res, next) => {
    // this call is not blocking, the configuration will be updated asynchronously
    appConfig.refresh();
    next();
});

server.get("/Beta", async (req, res) => {
    if (await featureManager.isEnabled("Beta")) {
        res.send("Welcome to the Beta page!");
    } else {
        res.status(404).send("Page not found");
    }
});

لمزيد من المعلومات حول كيفية استخدام مكتبة إدارة ميزات JavaScript، انتقل إلى البدء السريع لعلامة الميزة.

مرجع Key Vault

يدعم Azure App Configuration الرجوع إلى الأسرار المخزنة في Azure Key Vault. في App Configuration، يمكنك إنشاء مفاتيح تعين البيانات السرية المخزنة في Key Vault. يتم تخزين الأسرار بأمان في Key Vault، ولكن يمكن الوصول إليها مثل أي تكوين آخر بمجرد تحميلها.

تسترد مكتبة موفر التكوين مراجع Key Vault، تماما كما تفعل مع أي مفاتيح أخرى مخزنة في App Configuration. نظرا لأن العميل يتعرف على المفاتيح كمراجع Key Vault، فإن لديهم نوع محتوى فريدا، وسيتصل العميل ب Key Vault لاسترداد قيمهم لتطبيقك. تحتاج إلى تكوين الخاصية AzureAppConfigurationOptions.KeyVaultOptions باستخدام بيانات الاعتماد المناسبة للسماح لموفر التكوين بالاتصال ب Azure Key Vault.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential
    }
});

يمكنك أيضا توفير SecretClient مثيل مباشرة إلى KeyVaultOptions. بهذه الطريقة، يمكنك تخصيص الخيارات أثناء إنشاء SecretClient.

import { SecretClient } from "@azure/keyvault-secrets";

const credential = new DefaultAzureCredential();
const secretClient = new SecretClient(keyVaultUrl, credential, {
    serviceVersion: "7.0",
});
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretClients: [ secretClient ]
    }
});

يمكنك أيضا تعيين secretResolver خاصية لحل الأسرار التي لا تحتوي على Key Vault مقترن بها محليا.

const resolveSecret = (url) => "From Secret Resolver";
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        secretResolver: resolveSecret
    }
});

يمكنك أيضا تعيين clientOptions خاصية للتكوين SecretClientOptions المستخدم للاتصال ب Azure Key Vault الذي لم يتم تسجيله SecretClient.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        clientOptions: { // configure a custom SecretClientOptions
            retryOptions: { 
                maxRetries: 3, 
                maxRetryDelayInMs: 1000 
            }
        }
    }
});

دقة سرية متوازية

لا يوفر Azure Key Vault واجهة برمجة تطبيقات دفعية لاسترداد أسرار متعددة في طلب واحد. عندما يحتاج تطبيقك إلى تحميل العديد من مراجع Key Vault، يمكنك تحسين الأداء عن طريق تمكين دقة البيانات السرية المتوازية باستخدام الخاصية parallelSecretResolutionEnabled في KeyVaultOptions. يسمح هذا للموفر بإحضار أسرار متعددة بالتوازي بدلا من التسلسل:

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        parallelSecretResolutionEnabled: true
    }
});

إشعار

عند حل البيانات السرية بالتوازي، قد تواجه حد خدمة Azure Key Vault. لمعالجة التقييد بشكل فعال، قم بتنفيذ أفضل ممارسات التقييد من جانب العميل عن طريق تكوين خيارات إعادة المحاولة المناسبة SecretClientل . يمكنك إما تسجيل مثيلات مخصصة SecretClient أو التكوين clientOptions عبر AzureAppConfigurationOptions.keyVaultOptions.

تحديث البيانات السرية ل Key Vault

يمكنك Azure App Configuration من تكوين فواصل التحديث السرية بشكل مستقل عن دورة تحديث التكوين. هذا أمر بالغ الأهمية للأمان لأنه في حين أن URI المرجعي ل Key Vault في تكوين التطبيق لا يزال دون تغيير، قد يتم تدوير السر الأساسي في Key Vault كجزء من ممارسات الأمان الخاصة بك.

للتأكد من أن تطبيقك يستخدم دائما أحدث القيم السرية، قم بتكوين الخاصية secretRefreshIntervalInMs في KeyVaultOptions. يفرض هذا على الموفر استرداد قيم سرية جديدة من Key Vault عندما:

استدعاءات التطبيق الخاص بك AzureAppConfiguration.refresh
انقضى الفاصل الزمني للتحديث المكون للسر

تعمل هذه الآلية حتى عندما لا يتم الكشف عن أي تغييرات في متجر App Configuration الخاص بك، ما يضمن بقاء تطبيقك متزامنا مع البيانات السرية التي تم تدويرها.

const credential = new DefaultAzureCredential();
const appConfig = await load(endpoint, credential, {
    keyVaultOptions: {
        credential: credential,
        secretRefreshIntervalInMs: 7200_000 // 2 hours
    }
});

اللقطة

اللقطة هي مجموعة فرعية مسماة وغير قابلة للتغيير لقيم مفاتيح متجر App Configuration. يتم اختيار قيم المفاتيح التي تشكل لقطة أثناء وقت الإنشاء من خلال استخدام عوامل تصفية المفتاح والتسمية. بمجرد إنشاء لقطة، يتم ضمان بقاء قيم المفاتيح داخل دون تغيير.

يمكنك استخدام محدد اللقطة لتحميل قيم المفاتيح أو علامات الميزات من لقطة:

const appConfig = await load(endpoint, credential, {
    selectors: [
        { snapshotName: "MySnapshot" }, // load key-values from snapshot
        { keyFilter: "test*", labelFilter: "test" }
    ],
    featureFlagOptions: {
        enabled: true,
        selectors: [
            { snapshotName: "MySnapshot" }, // load feature flags from snapshot
            { keyFilter: "*", labelFilter: "test" }
        ]
    }
});

إعادة محاولة بدء التشغيل

تحميل التكوين هو عملية مسار مهمة أثناء بدء تشغيل التطبيق. لضمان الموثوقية، ينفذ موفر Azure App Configuration آلية إعادة محاولة قوية أثناء تحميل التكوين الأولي. يساعد هذا في حماية التطبيق الخاص بك من مشكلات الشبكة العابرة التي قد تمنع بدء التشغيل الناجح.

يمكنك تخصيص هذا السلوك عبر AzureAppConfigurationOptions.startupOptions:

const appConfig = await load(endpoint, credential, { 
    startupOptions: { 
        timeoutInMs: 300_000
    }
});

النسخ الجغرافي المتماثل

للحصول على معلومات حول استخدام النسخ المتماثل الجغرافي، انتقل إلى تمكين النسخ المتماثل الجغرافي.

الخطوات التالية

لمعرفة كيفية استخدام موفر تكوين JavaScript، تابع إلى البرنامج التعليمي التالي.

استخدام التكوين الديناميكي في JavaScript

لمعرفة كيفية استخدام مكتبة إدارة ميزات JavaScript، تابع إلى الوثائق التالية.

إدارة ميزات JavaScript

الملاحظات

هل كانت هذه الصفحة مفيدة؟

Last updated on 2025-09-22

مشاركة عبر

موفر تكوين JavaScript

تحميل التكوين

استهلاك التكوين

معالجة نوع محتوى JSON

تحميل قيم مفاتيح محددة باستخدام المحددات

عوامل تصفية العلامات

اقتطاع البادئة من المفاتيح

تحديث التكوين

تحديث مخصص لرد الاتصال

التحديث على مفتاح sentinel

علامة الميزة

إدارة الميزات

مرجع Key Vault

دقة سرية متوازية

تحديث البيانات السرية ل Key Vault

اللقطة

إعادة محاولة بدء التشغيل

النسخ الجغرافي المتماثل

الخطوات التالية

الملاحظات

الموارد الإضافية