[[["易于理解","easyToUnderstand","thumb-up"],["解决了我的问题","solvedMyProblem","thumb-up"],["其他","otherUp","thumb-up"]],[["很难理解","hardToUnderstand","thumb-down"],["信息或示例代码不正确","incorrectInformationOrSampleCode","thumb-down"],["没有我需要的信息/示例","missingTheInformationSamplesINeed","thumb-down"],["翻译问题","translationIssue","thumb-down"],["其他","otherDown","thumb-down"]],["最后更新时间 (UTC)：2025-08-12。"],[[["\u003cp\u003eMacros are placeholders, denoted by \u003ccode\u003e${ }\u003c/code\u003e, used within Cloud Data Fusion plugin properties for dynamic configuration, replacing them with actual values at runtime.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003elogicalStartTime()\u003c/code\u003e macro function retrieves the pipeline's run start time, allowing for optional parameters like time format, offset, and timezone, and is commonly used in file paths and to add timestamps to records.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003esecure()\u003c/code\u003e macro function accesses sensitive data from the Secure Store, using a provided key to substitute the corresponding value, which is useful for credentials like database passwords.\u003c/p\u003e\n"],["\u003cp\u003eMacros can refer to other macros up to ten levels deep, creating a recursive macro structure that evaluates from the innermost to the outermost macro.\u003c/p\u003e\n"]]],[],null,["# Macros and macro functions\n\nMacros are placeholders within the Cloud Data Fusion plugin property\nconfigurations. They're represented by variables enclosed within `${ }`, such as\n`${input_file_path}`. To enable dynamic configuration for elements, such as file\npaths and table names, the placeholders are replaced with actual values at\nruntime.\n\nWhen viewing a plugin's properties, you can add a macro to any property field\nthat has an **M** next to it. To add the macro, click the **M**.\n\nFor more information, see [Manage macros, preferences, and runtime arguments](/data-fusion/docs/how-to/manage-macros-prefs-and-runtime-args).\n\nMacro functions\n---------------\n\nIn addition to macros, you can use the following predefined macro functions:\n\n- `logicalStartTime()`\n- `secure()`\n\n### Logical Start Time function\n\nThe `logicalStartTime()` macro function returns the logical start time of a run\nof the pipeline as a string value.\n\nIf no parameters are supplied, it returns the start time in milliseconds. All\nparameters are optional. The function takes a time format, an offset, and a\ntimezone as arguments and uses the logical start time of a pipeline to perform\nthe substitution: \n\n ${logicalStartTime([timeFormat[,offset [,timezone])}\n\nThe following list shows the optional parameters for `logicalStartTime()`:\n\n**Example**\n\nIn this example, the logical start time of a pipeline run is\n`2020-01-01T00:00:00` and you provide the following macro: \n\n ${logicalStartTime(yyyy-MM-dd'T'HH-mm-ss,1d-4h+30m)}\n\nThe format is `yyyy-MM-dd'T'HH-mm-ss` and the offset is `1d-4h+30m` before the\nlogical start time. At runtime, the macro value is replaced with\n`2019-12-31T03:30:00` because the offset translates to 20.5 hours. The entire\nmacro evaluates to 20.5 hours before midnight of January 1, 2020.\n| **Note:** `logicalStartTime` is case sensitive. For example, if you enter `${logicalstarttime()}`, the pipeline fails. You must type `${logicalStartTime()}`.\n\n### Using `logicalStartTime()` in file-based plugins\n\nThe most common way to use this function is in the **Path** field in file-based\nplugins.\n\n#### Including the pipeline start time in milliseconds in a filename\n\nTo capture the actual start time in milliseconds in a filename, omit parameters\nin the macro function.\n\n**Example**\n\nIn this example, you include the pipeline start time, in milliseconds, in an\nAmazon S3 filename: \n\n sales_012345671011.csv\n\nIn the Amazon S3 sink properties, enter the following value in the **Path**\nfield: \n\n s3a://sales-data/sales_${logicalStartTime()}.csv\n\n#### Including the today's date in a filename\n\nYou can use the `logicalStartTime()` macro function in a filename to capture the\ncurrent date.\n\n**Example**\n\nIn this example, you capture today's date in the following S3 filename: \n\n s3a://sales-data/sales_20210204.csv\n\nIn the Amazon S3 sink properties, enter the following value in the **Path**\nfield: \n\n s3a://sales-data/sales_${logicalStartTime(yyyyMMdd)}.csv\n\n### Using `logicalStartTime` to add a Timestamp field to structured records\n\nYou can add timestamp to a structured record using the **Add Field**\ntransformation and `logicalStartTime()`.\n\n1. Get the **Field Adder Transform** plugin from Cloud Data Fusion Hub. After you deploy the plugin, it appears in the **Transform** list as **Add\n Field**.\n2. When you configure the plugin properties, add the timestamp to a structured record---for example, for the field name, enter the name of the new field and for the field value, enter the `logicalStartTime()` macro function.\n\n### Secure function\n\nThe `secure()` macro function takes in a single key as an argument and looks up\nthe key's associated string value from the [Secure Store](https://cdap.atlassian.net/wiki/spaces/DOCS/pages/480347053).\nTo perform the substitution, the [key](https://cdap.atlassian.net/wiki/spaces/DOCS/pages/801767425) provided as an argument must already\nexist in the Secure Store. This is useful for performing a substitution with\nsensitive data.\n\n**Example**\n\nIn this example, for a plugin that connects to a MySQL database, you configure\nthe password property field with the following value: \n\n ${secure(password)}\n\nThis macro pulls the password from the Secure Store at runtime.\n\nRecursive macros\n----------------\n\nMacros can recursively refer to other macros up to ten levels. Macro\narguments are evaluated from the innermost to the outermost argument.\n\n**Example**\n\nIn this example, you have a server that refers to a hostname and a port. You\nsupply the following runtime arguments, the last of which is a macro that refers\nto other macros:\n\n- **hostname** : `examplepetstore.com`\n- **port** : `9991`\n- **server-address** : `${hostname}:${port}`\n\nIn a pipeline configuration, you use the following expression: \n\n server-address: ${server-address}\n\nAt runtime, it's replaced with the following value: \n\n examplepetstore.com:9991\n\nWhat's next\n-----------\n\n- Learn more about [macros, preferences, and runtime arguments](/data-fusion/docs/how-to/manage-macros-prefs-and-runtime-args).\n\n- Learn how to use [plugin templates](/data-fusion/docs/how-to/create-plugin-templates)."]]
