Gunakan parameter kustom dengan template Resource Manager

BERLAKU UNTUK:Azure Data Factory Azure Synapse Analytics

Tip

Cobalah Data Factory di Microsoft Fabric, solusi analitik all-in-one untuk perusahaan. Microsoft Fabric mencakup semuanya mulai dari pergerakan data hingga ilmu data, analitik real time, kecerdasan bisnis, dan pelaporan. Pelajari cara memulai uji coba baru secara gratis!

Jika instance pengembangan Anda memiliki repositori Git terkait, Anda dapat mengganti parameter template Resource Manager default dari template Resource Manager yang dihasilkan dengan mempublikasikan atau mengekspor template. Sebaiknya Anda mengganti konfigurasi parameter Resource Manager default dalam skenario berikut:

• Gunakan CI/CD otomatis dan ubah beberapa properti selama penyebaran Resource Manager, tetapi parameter properti tidak dibuat secara default.

• Pabrik Anda sangat besar sehingga templat Resource Manager default tidak valid karena memiliki lebih dari parameter maksimum yang diizinkan (256).

  Untuk menangani batas parameter kustom 256, ada tiga opsi:

  • Gunakan file parameter kustom dan hapus properti yang tidak memerlukan parameterisasi, yaitu properti yang dapat mempertahankan nilai default dan karenanya mengurangi jumlah parameter.
  • Refaktor logika dalam aliran data untuk mengurangi parameter, misalnya, parameter alur semuanya memiliki nilai yang sama, Anda hanya cukup menggunakan parameter global.
  • Pisahkan satu pabrik data menjadi beberapa pabrik data.

Untuk mengganti konfigurasi parameter Resource Manager default, buka hub Kelola dan pilih templat ARM di bagian "Kontrol sumber". Di bagian Konfigurasi parameter ARM, klik ikon Edit di "Edit konfigurasi parameter" untuk membuka editor kode konfigurasi parameter Resource Manager.

Catatan

Konfigurasi parameter ARM hanya diaktifkan dalam “mode GIT”. Saat ini dinonaktifkan dalam "mode langsung" atau "mode Data Factory".

Jika konfigurasi parameter Resource Manager kustom dibuat, file bernama arm-template-parameters-definition.jsdi akan dihasilkan dalam folder akar cabang git Anda. Anda harus menggunakan nama file yang sama persis.

Saat menerbitkan dari cabang kolaborasi, Data Factory akan membaca file ini dan menggunakan konfigurasinya untuk menghasilkan properti yang parameternya akan dibuat. Jika file tidak ditemukan, templat default akan digunakan.

Saat mengekspor templat Resource Manager, Data Factory membaca file ini dari cabang mana pun yang sedang Anda kerjakan, bukan cabang kolaborasi. Anda dapat membuat atau mengedit file dari cabang privat, tempat Anda dapat menguji perubahan dengan memilih Ekspor Templat ARM di UI. Kemudian, Anda dapat menggabungkan file ke dalam cabang kolaborasi.

Catatan

Konfigurasi parameter Resource Manager kustom tidak mengubah batas parameter templat ARM 256. Dengan demikian, Anda dapat memilih dan mengurangi jumlah properti berparameter.

Sintaks parameter kustom

Berikut adalah panduan yang harus diikuti saat membuat file parameter kustom, arm-template-parameters-definition.json. File ini terdiri dari bagian untuk setiap jenis entitas: pemicu, alur, layanan tertaut, himpunan data, runtime integrasi, dan aliran data.

• Masukkan jalur properti di bawah jenis entitas yang relevan.
• Mengatur nama properti ke * menunjukkan bahwa Anda ingin membuat parameter semua properti di bawahnya (hanya turun ke tingkat pertama, tidak secara rekursif). Anda juga dapat menyertakan pengecualian untuk konfigurasi ini.
• Mengatur nilai properti sebagai string menunjukkan bahwa Anda ingin membuat parameter properti. Gunakan format <action>:<name>:<stype>.
  • <action> bisa menjadi salah satu karakter ini:
    • = berarti mempertahankan nilai saat ini sebagai nilai default untuk parameter.
    • - berarti tidak mempertahankan nilai default untuk parameter.
    • | adalah kasus khusus untuk rahasia dari Azure Key Vault untuk kunci atau string koneksi.
  • <name> adalah nama parameter. Jika kosong, nama properti akan dipilih. Jika nilainya dimulai dengan karakter -, nama akan disingkat. Misalnya, AzureStorage1_properties_typeProperties_connectionString akan disingkat menjadi AzureStorage1_connectionString.
  • <stype> adalah jenis parameter. Jika <stype> kosong, jenis defaultnya adalah string. Nilai yang didukung: string, securestring, int, bool, object, secureobject, dan array.
• Menentukan larik dalam file definisi menunjukkan bahwa properti yang cocok dalam templat adalah larik. Data Factory melakukan mengulangi semua objek dalam larik dengan menggunakan definisi yang ditentukan dalam objek runtime integrasi larik. Objek kedua, string, menjadi nama properti, yang digunakan sebagai nama untuk parameter untuk setiap perulangan.
• Definisi tidak boleh spesifik untuk instans sumber daya. Definisi apa pun berlaku untuk semua sumber daya dengan jenis tersebut.
• Secara default, semua string aman, seperti rahasia Key Vault, dan string aman, seperti string koneksi, kunci, dan token, diparameterkan.

Contoh templat parameterisasi

Berikut adalah contoh tampilan konfigurasi parameter Resource Manager. Parameter ini berisi contoh sejumlah kemungkinan penggunaan, termasuk parameterisasi aktivitas bertumpuk dalam alur dan mengubah defaultValue parameter layanan tertaut.

{
    "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": "="
            }
        }
    }
}

Berikut adalah penjelasan tentang cara templat sebelumnya disusun, yang diperinci berdasarkan jenis sumber daya.

Pipelines

• Properti apa pun di jalur activities/typeProperties/waitTimeInSeconds tersebut diparameterkan. Setiap aktivitas dalam alur yang memiliki properti tingkat kode bernama waitTimeInSeconds (misalnya, aktivitas Wait) diparameterkan sebagai angka, dengan nama default. Tapi, hal ini tidak akan memiliki nilai default di templat Resource Manager. Ini akan menjadi input wajib selama penyebaran Resource Manager.
• Demikian pula, properti bernama headers (misalnya, dalam aktivitas Web) diparameterkan dengan jenis object (JObject). Ini memiliki nilai default, yang merupakan nilai yang sama dengan pabrik sumber.

IntegrationRuntimes

• Semua properti di bawah jalur typeProperties diparameterkan dengan nilai default masing-masing. Misalnya, ada dua properti di bawah properti jenis IntegrationRuntimes: computeProperties dan ssisProperties. Kedua jenis properti dibuat dengan jenis dan nilai default masing-masing (Objek).

Memicu

• Di bawah typeProperties, dua properti diparameterkan. Yang pertama adalah maxConcurrency, yang ditentukan untuk memiliki nilai default dan berjenisstring. Properti Ini memiliki nama parameter default <entityName>_properties_typeProperties_maxConcurrency.
• Properti recurrence juga diparameterkan. Di bawahnya, semua properti pada tingkat tersebut ditentukan untuk diparameterkan sebagai string, dengan nama parameter dan nilai default. Pengecualiannya adalah properti interval, yang diparameterkan sebagai tipe int. Nama parameter diakhiri dengan <entityName>_properties_typeProperties_recurrence_triggerSuffix. Demikian pula, properti freq adalah string dan diparameterkan sebagai string. Namun, properti freq diparameterkan tanpa nilai default. Namanya disingkat dan diberi akhiran. Contohnya, <entityName>_freq.

LinkedServices

• Layanan tertaut bersifat unik. Karena himpunan data dan layanan tertaut memiliki beragam jenis, Anda dapat memberikan kustomisasi khusus jenis. Dalam contoh ini, untuk semua layanan tertaut dengan jenis AzureDataLakeStore, templat tertentu akan diterapkan. Untuk semua layanan lainnya (melalui *), templat yang berbeda akan diterapkan.
• Properti connectionString akan diparameterkan sebagai nilai securestring. Properti ini tidak akan memiliki nilai default. Ini akan memiliki nama parameter yang dipersingkat yang diakhiri dengan connectionString.
• Properti secretAccessKey kebetulan merupakan AzureKeyVaultSecret (misalnya, dalam layanan tertaut Amazon S3). Properti ini otomatis diparameterkan sebagai rahasia Azure Key Vault dan diambil dari brankas kunci yang dikonfigurasi. Anda juga dapat membuat parameter brankas kunci itu sendiri.

Himpunan data

• Meskipun kustomisasi khusus jenis tersedia untuk himpunan data, Anda dapat memberikan konfigurasi tanpa secara eksplisit memiliki *-konfigurasi tingkat. Dalam contoh sebelumnya, semua properti himpunan data di bawah typeProperties diparameterkan.

Catatan

Jika Pemberitahuan dan matriks Azure dikonfigurasi untuk alur, saat ini keduanya tidak didukung sebagai parameter untuk penyebaran ARM. Untuk menerapkan ulang pemberitahuan dan matriks dalam lingkungan baru, lihat Pemberitahuan, Matriks, dan Pemantauan Data Factory.

Templat parameterisasi default

Berikut adalah templat parameterisasi default saat ini. Jika Anda perlu menambahkan beberapa parameter saja, mengedit templat ini secara langsung mungkin merupakan ide yang baik karena Anda tidak akan kehilangan struktur parameterisasi yang sudah ada.

{
    "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": {
            "*": "="
        }
    }
}

Contoh: Membuat parameter ID kluster interaktif Azure Databricks yang ada

Contoh berikut menunjukkan cara menambahkan satu nilai ke templat parameterisasi default. Kami hanya ingin menambahkan ID kluster interaktif Azure Databricks yang sudah ada untuk layanan tertaut Databricks ke file parameter. Perhatikan bahwa file ini sama dengan file sebelumnya kecuali untuk penambahan existingClusterId di bagian bidang properti 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": "="
                }
            }
        }}
}

Konten terkait

• Gambaran umum integrasi dan pengiriman berkelanjutan
• Mengotomatiskan integrasi berkelanjutan menggunakan rilis Azure Pipelines
• Mempromosikan template Resource Manager secara manual ke setiap lingkungan
• Templat Resource Manager tertaut
• Menggunakan lingkungan produksi perbaikan
• Sampel skrip pra dan pos penerapan