SSISDB6：參數和環境變量

SSISDB 系列隨筆匯總：

• SSISDB1：使用SSISDB管理Package
• SSISDB2：SSIS工程的操作實例
• SSISDB3：Package的執行實例
• SSISDB4：當前正在運行的Package及其Executable
• SSISDB5：使用TSQL腳本執行Package
• SSISDB6：參數和環境變量

 

參數（Parameter）是Package暴露給外界的接口，通過傳遞不同的參數值，能夠控制 Package 的執行流程，執行不同的任務（Task）。參數分為Package級別的參數（Package Parameter）和工程級別的參數（Project Parameter），Package參數只能作用於當前的Package，而Project參數能夠作用於當前Project中包含的所有Package。參數的值只能引用，不能修改。

參數除了直接賦值之外，還能通過環境變量來賦值。環境是變量的集合，參數引用不同環境中的變量，能夠快速切換Package引用的參數值，例如，在測試環境和產品環境之間快速切換，這是參數化編程帶來的便利。

一，參數的值

參數有三種類型的值：design_default_value，Default_Value 和 Execution_Value：

• design_default_value：在設計SSIS Project時，設置parameter的默認值。
• Default_Value：在project 部署到SSISDB后，如果不對Parameters value進行修改，那么 Default_Value 和 design_default_value 相同；也可以修改Parameter的default value。
• Execution_Value：Package 在執行時，parameters的值是Execution Value。默認情況下，Package在執行時，使用default value作為execution value；也可以在啟動Execution時，設置Parameter的值，修改Execution Value不會修改Default value。

用戶可以創建參數和環境之間的映射，Package在執行時，引用環境（Environment）中的變量（Variables）為參數賦值。

1，查看參數的設計值（design_default_value） 和默認值（Default_Value）

select f.name as folder_name,
    p.name as project_name, 
    op.parameter_id,
    op.parameter_name,
    case op.object_type
        when 20 then 'Project'
        when 30 then 'Package'
        else ''
    end as  object_type,
    op.object_name,
    op.data_type,
    op.required,
    op.sensitive,
    op.design_default_value,
    op.default_value,
    case op.value_type
        when 'V' then 'parameter_value is a literal value'
        when 'R' then 'referencing an environment variable'
        else ''
    end as value_type,
    op.value_set,
    op.referenced_variable_name
from catalog.object_parameters op
inner join catalog.projects p 
    on op.project_id=p.project_id
inner join catalog.folders f 
    on p.folder_id=f.folder_id
where op.object_type in(20,30)

2，查看參數的執行值（Execution_Value）

select epv.execution_parameter_id,
    case epv.object_type
        when 20 then 'Project'
        when 30 then 'Package'
        when 50 then 'Special'
        else ''
    end as  object_type,
    epv.parameter_data_type,
    epv.parameter_name,
    epv.parameter_value,
    epv.sensitive,
    epv.required,
    epv.value_set,
    epv.runtime_override
from catalog.execution_parameter_values epv 
where execution_id=104627

3，通過TSQL來設置參數的執行值（Execution value）

declare @Execution_ID bigint
exec catalog.create_execution @package_name=N'Test.dtsx',
    @Execution_ID=@Execution_ID output,
    @folder_name=N'MyProjectFloder',
    @project_name=N'MyProject',
    @use32bitruntime=FALSE,
    @reference_id=null

declare @var0 sql_variant=N'Package_Parameter_value';
exec catalog.set_execution_parameter_value 
    @Execution_ID=@Execution_ID,
    @object_type=30,        --Package
    @parameter_name=N'Package_Parameter_Name',
    @parameter_value=@var0

exec catalog.start_execution @Execution_ID=@Execution_ID

二，參數的屬性

參數有兩種作用域：Project Scope 和 Package Scope。Project Scope用於Project中的所有package，而Package Scope只能用於當前Package，package只能引用 Parameter的值，不能修改。

Sensitive：敏感性，對於敏感參數，SSIS對值進行加密。

Required：必需性，對於必需參數，在執行時，必須設置值；在Create Agent時，必須顯式為必需參數賦值。

三，特殊參數

SSISDB的特殊參數，用於控制Package執行時的特殊行為，這些參數的值，通過 catalog.set_execution_parameter_value 來設置，參數 @object_type必須為50.

• LOGGING_LEVEL
• CUSTOMIZED_LOGGING_LEVEL
• DUMP_ON_ERROR
• DUMP_ON_EVENT
• DUMP_EVENT_CODE
• CALLER_INFO
• SYNCHRONIZED

1，記錄日志的級別

LOGGING_LEVEL：設置執行實例的日志級別，有效值是0、1、2、3，數值越大，日志記錄的越詳細，分別是：不記錄（no Logging），基本（Basic），性能（Performance）和詳細（verbose ）。

2，Package執行的同步性

默認情況下，當使用 catalog.start_execution 執行一個Package的執行實例（Execution Instance）時，該sp會立即返回結果值（0，表示調用Package成功），而不會等待Package執行完成，如果將參數 SYNCHRONIZED  設置為1，那么該SP不會立即返回，而是等到Package執行完成之后，才返回結果。

exec catalog.set_execution_parameter_value
　  @execution_id, 
    @object_type= 50, 
    @parameter_name = N'Synchronized', 
    @parameter_value = 1;

3，創建用於調試的轉存文件

• DUMP_ON_ERROR：在Package發生錯誤時創建轉存文件
• DUMP_ON_EVENT：在觸發事件時創建轉存文件
• DUMP_EVENT_CODE：轉存事件代碼

4，查看特殊參數的執行值（Execution value）

select epv.execution_parameter_id,
    case epv.object_type
        when 20 then 'Project'
        when 30 then 'Package'
        when 50 then 'Special'
        else ''
    end as  object_type,
    epv.parameter_data_type,
    epv.parameter_name,
    epv.parameter_value,
    epv.sensitive,
    epv.required,
    epv.value_set,
    epv.runtime_override
from catalog.execution_parameter_values epv 
where execution_id=104627
    and epv.object_type=50

四，環境和環境變量

環境（Environment）是變量的集合，創建環境的目的是為了向環境中添加變量。在開發Package時，為了保證開發包的質量，需要把產品環境和測試環境獨立開來，包只有在測試環境中執行通過時，才能部署到產品環境中。這可以簡單的通過修改鏈接管理器（Connection Manager）來實現。但是，當鏈接比較多時，或參數比較多時，在修改參數時，很容易出現錯誤。如果把Project和環境關聯起來，把環境中的變量和參數關聯起來。這樣，只需要修改Project引用的環境，就可以很容易地切換Package運行的環境。

1，創建環境

通過向導來創建環境，右擊“Environments”，點擊“Create Environment”，打開創建環境的向導，輸入環境名稱，點擊“OK”按鈕，創建環境：

2，向環境中添加變量

右擊新建的環境，點擊“Properties”，選擇“variables”頁，輸入變量的名稱，選擇變量的類型，輸入變量值，勾選變量的敏感（Sensitive）屬性：

3，設置Project引用環境

右擊工程名稱，點擊“Configure”，在“Parameters” Tab中查看工程的參數。

選擇“References” Tab，選擇project 引用的環境：

回到“Parameters”Tab，點擊value列后面的“...”，逐個設置工程參數應用的環境變量：

4，查看Project引用的環境

通過 catalog.environment_references 查看Project應用的環境，引用類型reference_type，當reference_type為A，表示使用絕對應用（absolute reference）；當reference_type為A，表示使用相對引用（relative reference）。相對引用表示環境和Project必須處於相同的Folder中；絕對引用表示環境和Project可以位於不同的Folder中，當然也可以位於相同的Folder中。

五，查看環境變量

1，參看參數 和環境變量的對應關系

--object_type : 20 (project parameter), 30 (package parameter)
--value_type: V (parameter_value is a literal value),R(referencing an environment variable)
--value_set:1(the parameter value has been assigned), 0 (the parameter value has not been assigned)

select op.project_id,
    p.name as ProjectName,
    op.object_type,        
    op.object_name,
    op.parameter_name,
    op.data_type,
    op.required,
    op.sensitive,
    op.design_default_value,
    op.default_value,
    op.value_type,
    op.referenced_variable_name,
    op.value_set
from [catalog].[object_parameters] op with(NOLOCK)
inner join catalog.projects p with(nolock)
    on op.project_id=p.project_id
where object_type in(20,30)

2，查看SSISDB的環境變量

select f.name as Folder_Name,e.name as Environment_Name,
    ev.variable_id,ev.name as Environment_Variable_Name,
    ev.sensitive,ev.type,ev.value
from catalog.environments e 
inner join catalog.environment_variables ev
    on e.environment_id=ev.environment_id
inner join catalog.folders f
    on e.folder_id=f.folder_id

3，查看Package 的參數和環境變量的映射關系

select er.environment_folder_name,er.environment_name,p.name as Project_Name,
    er.reference_type,
        ev.variable_id,ev.name as Environment_Variable_Name,
    ev.sensitive,ev.type,ev.value,
    op.parameter_id,op.object_type,op.object_name,op.parameter_name,
    op.data_type as Parameter_Data_Type,op.required,op.sensitive,
    op.default_value,op.design_default_value,op.value_set,op.value_type
from catalog.environment_references er
inner join catalog.projects p
    on er.project_id=p.project_id
inner join catalog.environments e 
    on er.environment_name= er.environment_name
inner join catalog.environment_variables ev
    on e.environment_id=ev.environment_id
inner join catalog.object_parameters op
    on op.project_id=p.project_id and op.value_type=N'R' and op.referenced_variable_name=ev.name

 

 

參考文檔：

catalog.object_parameters (SSISDB Database)

catalog.environment_references (SSISDB Database)

catalog.set_execution_parameter_value (SSISDB Database)

Quick Tip – Run SSIS 2012 packages synchronously and other execution parameters