使用参数和密钥

参数允许你在合成监控（synthetic monitors）中使用动态定义的值。例如，你可能希望使用特定的演示账号测试生产环境网站，而该账号的密码仅由管理合成监控的团队知晓。

有关安全敏感用例的更多信息，请参考 处理密钥和敏感值。

你可以通过以下任意方式声明参数值：

• 在可观测性项目中的 Synthetics 设置页面的全局参数（Global parameters）选项卡中。
• 在配置文件中为参数声明默认值。
• 传递 --params CLI 参数。

配置文件中的值按以下顺序读取：

1. 可观测性项目中的全局参数：首先读取通过 UI 设置的全局参数。
2. 配置文件：然后，将全局参数与配置文件中定义的任何参数合并。如果某个参数同时在可观测性 UI 和 Synthetics 项目配置文件中定义，则将使用配置文件中的值。
3. CLI：然后，将配置中定义的参数与传递给 CLI --params 参数的任何参数进行合并。如果某个参数同时在 Synthetics 项目配置文件 和 CLI 参数中定义，则将使用 CLI 定义的值。在使用 CLI 运行脚本时，Kibana 或可观测性 Serverless 项目中定义的全局参数对测试没有影响，因为测试无法访问 Kibana 或可观测性项目。

从 Synthetics UI 的任何页面

1. 转到 Settings（设置）。
2. 转到 Global parameters（全局参数）选项卡。
3. 定义参数。

×

默认情况下，自定义用户角色没有权限访问全局参数值。管理员可以通过向角色添加 Synthetics Can read global parameter values（可以读取全局参数值）Kibana 子功能权限来授予对全局参数的读取权限。添加后，用户可以使用 Get parameters API 或通过选择 图标来查看全局参数值。

要向角色添加 Can read global parameter values Kibana 权限：

1. 转到导航菜单中的 角色 管理页面，或使用 全局搜索栏。
2. 编辑现有角色或选择 Create role（创建角色）。
3. 在 Kibana 部分，选择 Add Kibana privilege（添加 Kibana 权限）。
4. 在 Kibana 权限列表中展开 Synthetics and Uptime。
5. 开启 Customize sub-feature privileges（自定义子功能权限）。
6. 开启 Can read global parameter values。

有关创建自定义角色的更多信息，请参考 定义角色。

使用 synthetics.config.js 或 synthetics.config.ts 文件来定义测试所需的变量。此文件应放置在 Synthetics 项目的根目录中。

export default (env) => {
  let my_url = "https://:8080";
  if (env === "production") {
    my_url = "https://elastic.github.io/synthetics-demo/"
  }
  return {
    params: {
      my_url,
    },
  };
};
		

上面的示例使用了 env 变量，该变量对应于 NODE_ENV 环境变量的值。

要在命令行上运行 npx @elastic/synthetics 时设置参数，请使用 --params 或 -p 标志。提供的映射将与 synthetics.config.{js,ts} 文件中定义的任何现有变量进行合并。

例如，要覆盖 my_url 参数，你可以运行

npx @elastic/synthetics . --params '{"my_url": "https://:8080"}'
		

你可以在 Synthetics 项目或 Synthetics UI 中创建的轻量级监控和浏览器监控中使用参数。

对于 Synthetics 项目中的轻量级监控，请将参数名称用 "${}" 包裹（例如 "${my_url}"）。

- type: http
  name: Todos Lightweight
  id: todos-lightweight
  urls: ["${my_url}"]
  schedule: '@every 1m'
		

在浏览器监控中，可以通过 journey、before、beforeAll、after 或 afterAll 回调函数的参数中可用的 params 属性来引用参数。

在参数名称前添加 params.（例如 params.my_url）

beforeAll(({params}) => {
  console.log(`Visiting ${params.my_url}`)
})

journey("My Journey", ({ page, params }) => {
  step('launch app', async () => {
    await page.goto(params.my_url)
  })
})
		

1. 如果你使用的是 TypeScript，请将 params.my_url 替换为 params.my_url as string。

要在 Synthetics UI 中创建的轻量级监控中使用参数，请将参数名称用 ${} 包裹（例如 ${my_url}）。

×

要在 Synthetics UI 中创建的浏览器监控中使用参数，请在参数名称前添加 params.（例如 params.my_url）。

×

你的 synthetics 脚本可能需要使用密码或其他在运行时才知道的敏感密钥。

如果你正在使用 Synthetics 项目管理监控，则可以在 synthetics.config.ts or synthetics.config.js 文件中使用环境变量。

下面的示例使用 process.env.MY_URL 引用在环境中定义的名为 MY_URL 的变量，并将其值赋给一个参数。然后，该参数可以在 Synthetics 项目中管理的轻量级监控和浏览器监控中使用

export default {
  params: {
    my_url: process.env.MY_URL
  }
};
		

如果你使用的是 Kibana 管理的监控并在私有位置上运行它们，则可以将环境变量直接注入到代理的运行时环境中。此方法允许你将敏感值排除在 Kibana UI 之外。相反，它将这些值存储在托管 Elastic Agent 的基础设施上。

使用 Docker 启动私有位置（Elastic Agent）时，请使用 --env 标志传递你的变量。

docker run \
  --env FLEET_ENROLL=1 \
  --env FLEET_URL={fleet_server_host_url} \
  --env FLEET_ENROLLMENT_TOKEN={enrollment_token} \
  --env MY_URL={secret_value} \
  --cap-add=NET_RAW \
  --cap-add=SETUID \
  -d --restart=unless-stopped \
  docker.elastic.co/elastic-agent/elastic-agent-complete:X.X.X
		

在 Kibana 的 Synthetics Monitors 编辑器中，你现在可以使用 process.env 访问这些变量。

step('navigate to secure url', async () => {
  // The script reads the environment variable from the private location elastic agent container
  await page.goto(process.env.MY_URL);
});