استخدم المعلمات المخصصة مع قالب Resource Manager

ينطبق على: Azure Data Factory Azure Synapse Analytics

تلميح

جرب Data Factory في Microsoft Fabric، وهو حل تحليلي متكامل للمؤسسات. يغطي Microsoft Fabric كل شيء بدءا من حركة البيانات إلى علم البيانات والتحليلات في الوقت الحقيقي والمعلومات المهنية وإعداد التقارير. تعرف على كيفية بدء إصدار تجريبي جديد مجانا!

إذا كان مثيل التطوير لديك يحتوي على مستودع Git مرتبط، فيمكنك تجاوز معلمات قالب Resource Manager الافتراضية لقالب Resource Manager الذي تم إنشاؤه عن طريق نشر القالب أو تصديره. قد تحتاج إلى تجاوز تكوين معلمة إدارة الموارد الافتراضية في هذه السيناريوهات:

• أنت تستخدم التكامل المستمر/التسليم المستمر التلقائي وتريد تغيير بعض الخصائص في أثناء توزيع Resource Manager، ولكن لا يتم تخصيص معلمات للخصائص بشكل افتراضي.

• المصنع كبير بحيث يكون قالب Resource Manager الافتراضي غير صالح لأنه يحتوي على أكثر من الحد الأقصى للمعلمات المسموح به (256).

  للتعامل مع حد 256 المعامل المخصص، هناك ثلاثة خيارات:

  • استخدم ملف المعلمة المخصصة وقم بإزالة الخصائص التي لا تحتاج إلى معلمات؛ أي الخصائص التي يمكنها الاحتفاظ بقيمة افتراضية ومن ثَمَّ تقليل عدد المعلمات.
  • منطق إعادة بناء العوامل في تدفق البيانات للحد من المعلمات. على سبيل المثال، في معلمات مسارات لها نفس القيمة، يمكنك فقط استخدام المعلمات العمومية بدلاً من ذلك.
  • تقسيم مصنع بيانات واحد إلى مصانع بيانات متعددة.

لتجاوز تكوين معلمة إدارة الموارد الافتراضية، انتقل إلى مركزManage وحدد ARM template في قسم "Source control". في قسم ARM parameter configuration انقر فوق رمزEdit في "Edit parameter configuration" لفتح محرر تعليمات برمجية لتكوين معلمة إدارة الموارد.

إشعار

يُمكن تكوين معلمة ARM فقط في "وضع GIT". وحالياً، معطل في وضع "Live mode" أو "Data Factory".

إنشاء تكوين معلمة إدارة موارد مخصصة ينشئ ملفاً يسمى arm-template-parameters-definition.json في المجلد الأصلي في فرع git. يجب عليك استخدام اسم الملف بالضبط.

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

عند تصدير قالب Resource Manager، يقوم Data Factory بقراءة هذا الملف من أي فرع تعمل عليه حاليًا، وليس من فرع التعاون. يمكنك إنشاء الملف أو تحريره من فرع خاص، حيث يمكنك اختبار التغييرات الخاصة بك عن طريق تحديد تصدير قالب ARM في واجهة المستخدم. ثم يمكنك دمج الملف في فرع التعاون.

إشعار

لا يؤدي تكوين معلمة Resource Manager المخصصة إلى تغيير حد معلمة قالب ARM البالغ 256. يتيح لك اختيار وتقليل عدد الخصائص محددة المعلمات.

بناء معلمة مخصصة

فيما يلي بعض الإرشادات التي يجب اتباعها عند إنشاء ملف المعلمات المخصصة، arm-template-parameters-definition.json. يتكون الملف من مقطع لكل نوع عنصر: المشغل، والمسار، والخدمة المرتبطة، ومجموعة البيانات، ووقت تشغيل التكامل، وتدفق البيانات.

• أدخل مسار الخصائص ضمن نوع العنصر ذي الصلة.
• يشير تعيين اسم خاصية إلى * أنك تريد تحديد معلمات لكافة الخصائص الموجودة تحته (فقط وصولا إلى المستوى الأول، وليس بشكل متكرر). يمكنك أيضًا تقديم استثناءات لهذا التكوين.
• تعيين قيمة خاصية كسلسلة يشير إلى أنك تريد تخصيص معلمات الخاصية. استخدم التنسيق <action>:<name>:<stype>.
  • <action> يمكن أن يكون أحد هذه الأحرف:
    • = يعني الاحتفاظ بالقيمة الحالية كقيمة افتراضية للمعلمة.
    • - يعني عدم الاحتفاظ بالقيمة الافتراضية للمعلمة.
    • |هي حالة خاصة للأسرار من Azure Key Vault سلسلة الاتصال أو المفاتيح.
  • <name> هو اسم المعلمة. إذا كان فارغًا، فإنه يأخذ اسم الخاصية. إذا بدأت القيمة بحرف - ، يتم تقصير الاسم. على سبيل المثال، AzureStorage1_properties_typeProperties_connectionString سيتم تقصير إلى AzureStorage1_connectionString.
  • <stype> هو نوع المعلمة. إذا كان <stype> فارغا، فإن النوع الافتراضي هو string. القيم المدعومة هي: string، securestring، int،bool،object،secureobject وarray.
• يشير تحديد صفيف في ملف التعريف إلى أن الخاصية المطابقة في القالب عبارة عن صفيف. يتكرر Data Factory خلال جميع الكائنات الموجودة في الصفيف باستخدام التعريف المحدد في كائن وقت تشغيل التكامل للصفيف. يصبح الكائن الثاني، السلسلة، اسم الخاصية، وهو يستخدم كاسم للمعلمة لكل تكرار.
• لا يمكن أن يكون التعريف محددًا بمثيل مورد. ينطبق أي تعريف على جميع الموارد من هذا النوع.
• بشكل افتراضي، يتم وضع معلمات لكل السلاسل الآمنة، مثل أسرار Vault Key، والسلاسل الآمنة، مثل سلاسل الاتصال والمفاتيح والرموز المميزة.

نموذج قالب المعلمات

فيما يلي مثال على الشكل الذي قد يبدو عليه تكوين معلمة Resource Manager. يحتوي على أمثلة لعدد من الاستخدامات المحتملة، بما في ذلك تحديد معلمات الأنشطة المتداخلة داخل البنية الأساسية وتغيير القيمة الافتراضية لمعلمة خدمة مرتبطة.

{
    "Microsoft.DataFactory/factories/pipelines": {
        "properties": {
            "activities": [{
                "typeProperties": {
                    "waitTimeInSeconds": "-::int",
                    "headers": "=::object",
                    "activities": [
                        {
                            "typeProperties": {
                                "url": "-:-webUrl:string"
                            }
                        }
                    ]
                }
            }]
        }
    },
    "Microsoft.DataFactory/factories/integrationRuntimes": {
        "properties": {
            "typeProperties": {
                "*": "="
            }
        }
    },
    "Microsoft.DataFactory/factories/triggers": {
        "properties": {
            "typeProperties": {
                "recurrence": {
                    "*": "=",
                    "interval": "=:triggerSuffix:int",
                    "frequency": "=:-freq"
                },
                "maxConcurrency": "="
            }
        }
    },
    "Microsoft.DataFactory/factories/linkedServices": {
        "*": {
            "properties": {
                "typeProperties": {
                    "accountName": "=",
                    "username": "=",
                    "connectionString": "|:-connectionString:secureString",
                    "secretAccessKey": "|"
                }
            }
        },
        "AzureDataLakeStore": {
            "properties": {
                "typeProperties": {
                    "dataLakeStoreUri": "="
                }
            }
        },
        "AzureKeyVault": {
            "properties": {
                "typeProperties": {
                    "baseUrl": "|:baseUrl:secureString"
                },
                "parameters": {
                    "KeyVaultURL": {
                        "type": "=",
                        "defaultValue": "|:defaultValue:secureString"
                    }
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/datasets": {
        "*": {
            "properties": {
                "typeProperties": {
                    "folderPath": "=",
                    "fileName": "="
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/credentials" : {
        "properties": {
            "typeProperties": {
                "resourceId": "="
            }
        }
    }
}

فيما يلي شرح لكيفية إنشاء النموذج السابق، مقسماً حسب نوع المورد.

التدفقات

• تُوضع معلمات على أي خاصية في activities/typeProperties/waitTimeInSeconds المسار. أي نشاط في مسارٍ يحتوي على خاصية مستوى التعليمات البرمجية المسماة waitTimeInSeconds (على سبيل المثال، Wait النشاط) توضع عليه معلمة كعدد، مع اسم افتراضي. ومع ذلك، لن تكون لها قيمة افتراضية في قالب Resource Manager. سيكون إدخالاً إلزامياً أثناء نشر إدارة الموارد.
• وبالمثل، تُوضع معلمة على خاصية تسمى headers (على سبيل المثال، في Web نشاط) مع نوع object (JObject). يتمتع بقيمة افتراضية، وهي نفس قيمة المصنع المصدر.

وقت تشغيل التكامل

• توضع معلمات على جميع الخصائص الموجودة ضمن المسار typeProperties مع القيم الافتراضية المعنية. على سبيل المثال، هناك اثنان من الخصائص تندرج تحت IntegrationRuntimes خصائص النوع: computeProperties وssisProperties . يُنشأ كلا النوعين من الخصائص مع القيم الافتراضية والأنواع الخاصة بهما (كائن).

أزرار التشغيل

• في typeProperties، تُوضع معلمات على خاصيتين. الأول هي maxConcurrency، الذي حُدد ليكون له قيمة افتراضية وهو من النوعstring. يحتوي على اسم المعلمة الافتراضي <entityName>_properties_typeProperties_maxConcurrency.
• recurrenceتُوضع معلمة أيضاً على الخاصية. وتحت هذه المعلمة، تحدد جميع الخصائص في هذا المستوى لتكون ذات معلمات كسلاسل، مع القيم الافتراضية وأسماء المعلمات. ويستثنى من ذلك intervalالخاصية، التي تُوضع عليها المعلمات كنوعٍint. تضاف لاحقة إلى اسم المعلمة، هي<entityName>_properties_typeProperties_recurrence_triggerSuffix. وبالمثل، فإن freq الخاصية هي سلسلة وتوضع عليها معلمات كسلسلة. ومع ذلك، freq توضع معلمات على الخاصية دون قيمة افتراضية. تم اختصار الاسم ولاحقه. على سبيل المثال، <entityName>_freq

LinkedServices

• الخدمات المرتبطة فريدة من نوعها. نظرا لأن الخدمات ومجموعات البيانات المرتبطة تحتوي على مجموعة واسعة من الأنواع، يمكنك توفير تخصيصات خاصة بنوع معين. في هذا المثال، سيطبق قالب معين AzureDataLakeStoreعلى جميع الخدمات المرتبطة من النوع. بالنسبة للبقية (* عبر)، سيُطبق قالب مختلف.
• connectionStringستوضع معلمات على الخاصية securestring كقيمة. لن تكون لها قيمة افتراضية. سيكون لها اسم معلمة مختصرة مضاف إليه لاحقة connectionString.
• يمكن أن تكون الخاصية secretAccessKeyAzureKeyVaultSecret (على سبيل المثال، في خدمة Amazon S3 المرتبطة). توضع المعلمات عليها تلقائياً كسر Azure Key Vault وتستخرج من key Vault المكونة. يمكنك أيضاً تحديد معلمات خزينة المفاتيح نفسها.

مجموعات البيانات

• على الرغم من أن التخصيص الخاص بنوع متاح لمجموعات البيانات، يمكنك توفير التكوين دون أن يكون لديك أي *-تكوين على مستوى. في المثال السابق، توضع معلمات على جميع خصائص مجموعة البيانات ضمن typeProperties.

إشعار

إذا كُوّن كل من تنبيهات Azure ومصفوفاته لمسار ما، فلن تكون مدعومة في الوقت الحالي كمعلمة لعمليات توزيع ARM. لإعادة تطبيق التنبيهات والمصفوفات في بيئة جديدة، يرجى اتباع مراقبة مصنع البيانات والتنبيهات والمصفوفات.

قالب المعلمات الافتراضي

يوجد أدناه نموذج المعلمات الافتراضي الحالي. إذا كنت بحاجة إلى إضافة بعض المعلمات فقط، فقد يكون تحرير هذا القالب مباشرة فكرة جيدة لأنك لن تفقد بنية المعلمات الموجودة.

{
    "Microsoft.DataFactory/factories": {
        "properties": {
            "globalParameters": {
                "*": {
                    "value": "="
                }
            }
        },
        "location": "="
    },
    "Microsoft.DataFactory/factories/globalparameters": {
        "properties": {
                "*": { 
                    "value": "=" 
                }
        }
    },
    "Microsoft.DataFactory/factories/pipelines": {
    },
    "Microsoft.DataFactory/factories/dataflows": {
    },
    "Microsoft.DataFactory/factories/integrationRuntimes":{
        "properties": {
            "typeProperties": {
                "ssisProperties": {
                    "catalogInfo": {
                        "catalogServerEndpoint": "=",
                        "catalogAdminUserName": "=",
                        "catalogAdminPassword": {
                            "value": "-::secureString"
                        }
                    },
                    "customSetupScriptProperties": {
                        "sasToken": {
                            "value": "-::secureString"
                        }
                    }
                },
                "linkedInfo": {
                    "key": {
                        "value": "-::secureString"
                    },
                    "resourceId": "="
                },
                "computeProperties": {
                    "dataFlowProperties": {
                        "externalComputeInfo": [{
                                "accessToken": "-::secureString"
                            }
                        ]
                    }
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/triggers": {
        "properties": {
            "pipelines": [{
                    "parameters": {
                        "*": "="
                    }
                }
            ],
            "pipeline": {
                "parameters": {
                    "*": "="
                }
            },
            "typeProperties": {
                "scope": "="
            }
        }
    },
    "Microsoft.DataFactory/factories/linkedServices": {
        "*": {
            "properties": {
                "typeProperties": {
                    "accountName": "=",
                    "username": "=",
                    "userName": "=",
                    "accessKeyId": "=",
                    "servicePrincipalId": "=",
                    "userId": "=",
                    "host": "=",
                    "clientId": "=",
                    "clusterUserName": "=",
                    "clusterSshUserName": "=",
                    "hostSubscriptionId": "=",
                    "clusterResourceGroup": "=",
                    "subscriptionId": "=",
                    "resourceGroupName": "=",
                    "tenant": "=",
                    "dataLakeStoreUri": "=",
                    "baseUrl": "=",
                    "database": "=",
                    "serviceEndpoint": "=",
                    "batchUri": "=",
                    "poolName": "=",
                    "databaseName": "=",
                    "systemNumber": "=",
                    "server": "=",
                    "url":"=",
                    "functionAppUrl":"=",
                    "environmentUrl": "=",
                    "aadResourceId": "=",
                    "sasUri": "|:-sasUri:secureString",
                    "sasToken": "|",
                    "connectionString": "|:-connectionString:secureString",
                    "hostKeyFingerprint": "="
                }
            }
        },
        "Odbc": {
            "properties": {
                "typeProperties": {
                    "userName": "=",
                    "connectionString": {
                        "secretName": "="
                    }
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/datasets": {
        "*": {
            "properties": {
                "typeProperties": {
                    "folderPath": "=",
                    "fileName": "="
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/managedVirtualNetworks/managedPrivateEndpoints": {
        "properties": {
            "*": "="
        }
    }
}

مثال: معلمة معرف مجموعة تفاعلي موجود في Azure Databricks

يوضح المثال التالي كيفية إضافة قيمة مفردة إلى قالب المعلمة الافتراضي. نريد فقط إضافة معرف مجموعة تفاعلي حالي من Azure Databricks لخدمة Databricks المرتبطة إلى ملف المعلمات. لاحظ أن هذا الملف هو نفس الملف السابق باستثناء إضافة existingClusterId ضمن حقل خصائص Microsoft.DataFactory/factories/linkedServices.

{
    "Microsoft.DataFactory/factories": {
        "properties": {
            "globalParameters": {
                "*": {
                    "value": "="
                }
            }
        },
        "location": "="
    },
    "Microsoft.DataFactory/factories/pipelines": {
    },
    "Microsoft.DataFactory/factories/dataflows": {
    },
    "Microsoft.DataFactory/factories/integrationRuntimes":{
        "properties": {
            "typeProperties": {
                "ssisProperties": {
                    "catalogInfo": {
                        "catalogServerEndpoint": "=",
                        "catalogAdminUserName": "=",
                        "catalogAdminPassword": {
                            "value": "-::secureString"
                        }
                    },
                    "customSetupScriptProperties": {
                        "sasToken": {
                            "value": "-::secureString"
                        }
                    }
                },
                "linkedInfo": {
                    "key": {
                        "value": "-::secureString"
                    },
                    "resourceId": "="
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/triggers": {
        "properties": {
            "pipelines": [{
                    "parameters": {
                        "*": "="
                    }
                }
            ],
            "pipeline": {
                "parameters": {
                    "*": "="
                }
            },
            "typeProperties": {
                "scope": "="
            }
 
        }
    },
    "Microsoft.DataFactory/factories/linkedServices": {
        "*": {
            "properties": {
                "typeProperties": {
                    "accountName": "=",
                    "username": "=",
                    "userName": "=",
                    "accessKeyId": "=",
                    "servicePrincipalId": "=",
                    "userId": "=",
                    "clientId": "=",
                    "clusterUserName": "=",
                    "clusterSshUserName": "=",
                    "hostSubscriptionId": "=",
                    "clusterResourceGroup": "=",
                    "subscriptionId": "=",
                    "resourceGroupName": "=",
                    "tenant": "=",
                    "dataLakeStoreUri": "=",
                    "baseUrl": "=",
                    "database": "=",
                    "serviceEndpoint": "=",
                    "batchUri": "=",
                    "poolName": "=",
                    "databaseName": "=",
                    "systemNumber": "=",
                    "server": "=",
                    "url":"=",
                    "aadResourceId": "=",
                    "connectionString": "|:-connectionString:secureString",
                    "existingClusterId": "-"
                }
            }
        },
        "Odbc": {
            "properties": {
                "typeProperties": {
                    "userName": "=",
                    "connectionString": {
                        "secretName": "="
                    }
                }
            }
        }
    },
    "Microsoft.DataFactory/factories/datasets": {
        "*": {
            "properties": {
                "typeProperties": {
                    "folderPath": "=",
                    "fileName": "="
                }
            }
        }}
}

المحتوى ذو الصلة

• نظرة عامة على التكامل المستمر والتسليم
• أتمتة التكامل المستمر باستخدام إصدارات مسارات Azure
• ترقية قالب Resource Manager يدوياً لكل بيئة
• قوالب Resource Manager المرتبطة
• استخدام بيئة إنتاج إصلاح عاجل
• نموذج البرنامج النصي قبل وبعد النشر