教程：使用定时触发器实现集群自动化

创建服务帐户。

要创建一个服务帐户，您的触发器可以使用该帐户来调用对现有Atlas项目具有Project Owner 权限的Atlas Administration API ：

1. 在 Atlas 中，转到 Users 页面。

   1. 如果尚未显示，组织从导航栏中的Organizations菜单。

   2. 单击 Identity & Access 部分下侧边栏中的 All Projects，然后选择所需的项目。

   3. 单击 Security 部分下侧边栏中的 Project Identity & Access。

   显示“用户”页面。

2. 单击Create ApplicationService Account 。

3. 输入服务帐户信息。

   • 名称：服务帐户的名称。 （例如，TriggersServiceAccount）

   • 描述：（可选）服务帐户的描述。 （例如，用于Atlas Functions 调用Atlas Administration API的服务帐号。）

   • 服务帐户权限： Project Owner

4. 单击 Create（连接）。

   这会创建服务帐户，并自动将其添加到具有Organization Member 权限的项目的父组织。

5. 配置 API Access List。

   如果要限制哪些IP地址可以使用此服务帐户调用Atlas Administration API ，请将IP地址添加到 API Access List。

   注意

   如果为您的组织启用了 Require IP Access List for the Atlas Administration API，或者您在服务帐户的 API Access List 中添加了任何IP地址，则每个Atlas Administration API请求都必须通过IP访问列表检查。

   Atlas Triggers和函数从一设立特定的出站IP地址发送传出HTTP请求。启用定时触发器能够调用Atlas Administration API和其他外部服务，您必须将这些IP地址添加到服务帐户的 API Access List 中。

   有关Atlas Function 使用的出站IP地址的完整列表，请参阅函数安全出站IP访问。您必须单独添加每个IP解决。

将服务帐户凭证存储为值和密钥。

创建以下值和密钥来存储您的服务帐户凭证：

• AtlasClientId 包含服务帐户客户端ID的值。

• AtlasClientSecret 包含服务帐户客户端密钥的密钥。

• AtlasClientSecret 链接到密钥的值。这样，您就可以访问权限函数中的客户端密钥值，同时仍将其安全地存储为密钥。

1. 在 Atlas 中，前往 Triggers 页面。

   1. 如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。

   2. 如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。

   3. 在侧边栏中，单击 Streaming Data 标题下的 Triggers。

   会显示触发器页面。

2. 导航至 Values 页面。

   1. 单击 Linked App Service: Triggers（管理员）链接。

   2. 在侧边栏中，单击 Build 标题下的 Values。

3. 将客户端ID存储在值中。

   1. 单击 Create a Value

   2. 输入 AtlasClientId 作为 Value Name。

   3. 选择 Value 类型。

   4. 选择Custom Content选项并输入客户端ID。

      注意

      您必须以带引号的字符串值形式输入客户端ID ("<clientId>")。

   5. 单击 Save（连接）。

4. 将客户端密钥存储在密钥中并将其链接到值。

   注意

   无法直接访问密钥值，因此您必须创建链接到该密钥的第二个值。

   1. 单击 Create a Value（连接）。

   2. 输入 AtlasClientSecret 作为 Value Name。

   3. 选择 Value 类型。

   4. 选择 Link to Secret 选项。

   5. 输入 AtlasClientSecret 并单击 Create "AtlasClientSecret" 为密钥值命名。

      将客户端密钥粘贴到密钥名称下方显示的 Client Secret字段中。

   6. 单击 Save 以创建密钥和值。

创建getAuthHeaders 函数。

要创建可重用的函数，该函数使用服务帐户凭证检索访问权限令牌并返回适当的身份验证标头以调用Atlas Administration API：

1. 导航至 Functions 页面。

   1. 在侧边栏中，单击 Build 标题下的 Functions。

   2. 单击 Create a Function（连接）。

      默认显示 Settings标签页。

2. 输入 getAuthHeaders 作为函数的 Name。

3. 将 Private 设置为 true。此函数只能由本教程中的其他函数调用。

   将 Settings标签页中的其他配置选项保留为默认值。

4. 定义函数代码。

   单击 Function Editor标签页并粘贴以下代码以定义函数：

   1
   /*
   2
    * Generate API request headers with a new Service Account Access Token.
   3
    */
   4
   exports = async function getAuthHeaders() {
   5
   6
     // Get stored credentials
   7
     clientId = context.values.get("AtlasClientId");
   8
     clientSecret = context.values.get("AtlasClientSecret");
   9
   10
     // Throw an error if credentials are missing
   11
     if (!clientId || !clientSecret) {
   12
       throw new Error("Authentication credentials not found. Set AtlasClientId/AtlasClientSecret (service account auth credentials).");
   13
     }
   14
   15
     // Define the argument for the HTTP request to get the access token
   16
     const tokenUrl = "https://cloud.mongodb.com/api/oauth/token";
   17
     const credentials = Buffer.from(`${clientId}:${clientSecret}`).toString("base64");
   18
   19
     const arg = {
   20
       url: tokenUrl,
   21
       headers: {
   22
         "Authorization": [ `Basic ${credentials}` ],
   23
         "Content-Type": [ "application/x-www-form-urlencoded" ]
   24
       },
   25
       body: "grant_type=client_credentials"
   26
     }
   27
   28
     // The response body is a BSON.Binary object; parse it to extract the access token 
   29
     const response = await context.http.post(arg);
   30
     const tokenData = JSON.parse(response.body.text());
   31
     const accessToken = tokenData.access_token;
   32
   33
     // Define the Accept header with the resource version from env var or default to latest stable
   34
     const resourceVersion = context.environment.ATLAS_API_VERSION || "2025-03-12";
   35
     const acceptHeader = `application/vnd.atlas.${resourceVersion}+json`;
   36
   37
     // Return the access token as headers for future API calls
   38
     return {
   39
      headers: {
   40
        "Authorization": [ `Bearer ${accessToken}` ],
   41
        "Accept": [ acceptHeader ],
   42
        "Accept-Encoding": [ "bzip, deflate" ],
   43
        "Content-Type": [ "application/json" ]
   44
      }
   45
     };
   46
   }

创建modifyCluster 函数。

要创建一个可重用函数来封装“在一个项目中更新一个集群”端点，请执行以下操作：

1. 在 Functions 页面中，单击 Create a Function。

   默认显示 Settings标签页。

2. 输入 modifyCluster 作为函数的 Name。

3. 将 Private 设置为 true。此函数只能由本教程中的其他函数调用。

   将 Settings标签页中的其他配置选项保留为默认值。

4. 定义函数代码。

   单击 Function Editor标签页并粘贴以下代码以定义函数：

   1
   /*
   2
    * Modifies the cluster as defined by the `body` parameter.
   3
    * See https://www.mongodb.com/zh-cn/docs/atlas/reference/api-resources-spec/v2/#tag/Clusters/operation/updateCluster
   4
    */
   5
   exports = async function(projectID, clusterName, body) {
   6
   7
     // Easy testing from the console
   8
     if (projectID === "Hello world!") {
   9
       projectID   = "<projectId>";
   10
       clusterName = "<clusterName>";
   11
       body        = { paused: false };
   12
     }
   13
   14
     // Retrieve headers to authenticate with a new access token, and define the request URL for the Atlas API endpoint
   15
     const authHeaders = await context.functions.execute("getAuthHeaders");
   16
     const requestUrl = `https://cloud.mongodb.com/api/atlas/v2/groups/${projectID}/clusters/${clusterName}`;
   17
   18
     // Build the argument for the HTTP request to the Atlas API to modify the cluster
   19
     const arg = {
   20
       url: requestUrl,
   21
       headers: authHeaders.headers,
   22
       body: JSON.stringify(body)
   23
     };
   24
   25
     // The response body is a BSON.Binary object; parse it and return the modified cluster description
   26
     const response = await context.http.patch(arg);
   27
     if (response.body) {
   28
        return EJSON.parse(response.body.text()); 
   29
     } else {
   30
        throw new Error(`No response body returned from Atlas API. Status code: ${response.status}`);
   31
     }
   32
   };

   注意

   在函数编辑器中测试代码。

   当您在 Testing Console 中运行函数时，Function Editor 会自动提供 "Hello world!" 作为第一个参数。此代码会测试该输入，并在收到 "Hello world!" 时为参数提供值。

   要使用自己的输入测试函数，请将以下占位符值替换为您自己的信息：

   • <projectId>

   • <clusterName>

   • 在 body 参数中，提供一个有效负载，其中包含您要对集群进行的修改。示例代码包含暂停集群的有效负载。

创建pauseClusters 函数。

1. 在 Atlas 中，前往 Triggers 页面。

   1. 如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。

   2. 如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。

   3. 在侧边栏中，单击 Streaming Data 标题下的 Triggers。

   会显示触发器页面。

2. 导航至Functions页面

   1. 单击 Linked App Service: Triggers（管理员）链接。

   2. 在侧边栏中，单击 Build 标题下的 Functions。

   3. 单击 Create a Function（连接）。

      默认显示 Settings标签页。

3. 输入 pauseClusters 作为函数的 Name。

4. 将 Private 设置为 true。在本教程中，此函数只会由 pauseClusters 触发器调用。

   将 Settings标签页中的其他配置选项保留为默认值。

5. 定义函数代码。

   单击 Function Editor标签页并粘贴以下代码以定义函数：

   1
   /*
   2
    * Iterates over the provided projects and clusters, pausing those clusters.
   3
    */
   4
   exports = async function () {
   5
   6
     // Supply project IDs and cluster names to pause
   7
     const projectIDs = [
   8
       {
   9
         id: "<projectIdA>",
   10
         names: [ "<clusterNameA>", "<clusterNameB>" ]
   11
       },
   12
       {
   13
         id: "<projectIdB>",
   14
         names: [ "<clusterNameC>" ]
   15
       }
   16
     ];
   17
   18
     // Set desired state
   19
     const body = { paused: true };
   20
   21
     // Pause each cluster and log the response
   22
     for (const project of projectIDs) {
   23
       for (const cluster of project.names) {
   24
         const result = await context.functions.execute(
   25
           "modifyCluster",
   26
           project.id,
   27
           cluster,
   28
           body,
   29
         );
   30
         console.log("Cluster " + cluster + ": " + EJSON.stringify(result));
   31
       }
   32
     }
   33
   34
     return "Clusters Paused";
   35
   };

   将 projectIDs大量替换为您自己的项目和集群名称。

   注意

   为避免项目和集群名称进行硬编码，您可以使用本教程末尾的辅助函数从Atlas Administration API中检索项目和集群列表，并以编程方式确定要按安排暂停和恢复的集群。

创建pauseClusters 定时触发器。

1. 在 Functions 页面中，单击 Build 标题下侧边栏中的 Triggers，导航到 Triggers 页面。

2. 单击 Create a Trigger 打开触发器配置页面。

   如果已有触发器，请单击 Add a Trigger

3. 配置触发器设置。

   在 Trigger Details 中，设立以下配置：

   设置	值
   触发器类型	預定
   进度表类型	高级。这允许您为安排指定 CRON表达式。 要在每个工作日的晚上 6 PM 美国东部时间（即 22:00 UTC）运行此命令，请使用以下 CRON表达式： 0 22 * * 1-5
   重新启用时跳过事件	打开。这可以防止触发器在禁用触发器时排队的计划上执行。
   eventType	函数。从下拉列表中选择 pauseClusters 函数。
   触发器名称	pauseClusters

4. 单击 Save 以创建触发器。

   现在，您的测试集群将在每天晚上美国东部时间下午 6 自动暂停。

创建resumeClusters 函数。

1. 将 pauseClusters 函数复制到名为 resumeClusters 的新函数中。

2. 在 Function Editor标签页中，在函数代码中将 paused 状态更新为 false：

   1
   /*
   2
    * Iterates over the provided projects and clusters, resuming those clusters.
   3
    */
   4
   exports = async function () {
   5
   6
     // Supply project IDs and cluster names to resume
   7
     const projectIDs = [
   8
       {
   9
         id: "<projectIdA>",
   10
         names: [ "<clusterNameA>", "<clusterNameB>" ]
   11
       },
   12
       {
   13
         id: "<projectIdB>",
   14
         names: [ "<clusterNameC>" ]
   15
       }
   16
     ];
   17
   18
     // Set desired state
   19
     const body = { paused: false };
   20
   21
     // Resume each cluster and log the response
   22
     for (const project of projectIDs) {
   23
       for (const cluster of project.names) {
   24
         const result = await context.functions.execute(
   25
           "modifyCluster",
   26
           project.id,
   27
           cluster,
   28
           body,
   29
         );
   30
         console.log("Cluster " + cluster + ": " + EJSON.stringify(result));
   31
       }
   32
     }
   33
   34
     return "Clusters Resumed";
   35
   };

创建resumeClusters 定时触发器。

1. 在 Functions 页面中，单击 Build 标题下侧边栏中的 Triggers，导航到 Triggers 页面。

2. 配置触发器设置。

   在 Trigger Details 中，设立以下配置：

   设置	值
   触发器类型	預定
   进度表类型	高级。这允许您为安排指定 CRON表达式。 要在每个工作日上午 8 AM 美国东部时间（即 12:00 UTC）运行此命令，请使用以下 CRON表达式： 0 12 * * 1-5
   重新启用时跳过事件	打开。这可以防止触发器在禁用触发器时排队的计划上执行。
   eventType	函数。从下拉列表中选择 resumeClusters 函数。
   触发器名称	resumeClusters

3. 单击 Save 以创建触发器。

现在，您的测试集群将在每天晚上暂停，并在每个工作日早上自动恢复。

创建scaleClusterUp 函数。

1. 在 Atlas 中，前往 Triggers 页面。

   1. 如果尚未显示，请从导航栏上的 Organizations 菜单中选择包含项目的组织。

   2. 如果尚未显示，请从导航栏的 Projects 菜单中选择您的项目。

   3. 在侧边栏中，单击 Streaming Data 标题下的 Triggers。

   会显示触发器页面。

2. 导航至Functions页面

   1. 单击 Linked App Service: Triggers（管理员）链接。

   2. 在侧边栏中，单击 Build 标题下的 Functions。

   3. 单击 Create a Function（连接）。

      默认显示 Settings标签页。

3. 输入 scaleClusterUp 作为函数的 Name。

4. 将 Private 设置为 true。在本教程中，此函数只会由 scaleClusterUp 触发器调用。

   将 Settings标签页中的其他配置选项保留为默认值。

5. 定义函数代码。

   在 Create Function 页面中，单击 Function Editor标签页并粘贴以下代码以定义函数：

   1
   /*
   2
    * Scales a single cluster up to a larger instance size.
   3
    * This example scales an AWS cluster up to M30 in region US_EAST_1.
   4
    */
   5
   exports = async function() {
   6
     // Supply project ID and cluster name...
   7
     const projectID   = "<projectId>";
   8
     const clusterName = "<clusterName>";
   9
   10
     // Set the desired instance size and topology...
   11
     const body = {
   12
       replicationSpecs: [
   13
         {
   14
           regionConfigs: [
   15
             {
   16
               electableSpecs: {
   17
                 instanceSize: "M30", // for example, larger tier
   18
                 nodeCount: 3
   19
               },
   20
               priority:     7,
   21
               providerName: "AWS",
   22
               regionName:   "US_EAST_1"
   23
             }
   24
           ]
   25
         }
   26
       ]
   27
     };
   28
   29
     // Scale up the cluster and log the response
   30
     const result = await context.functions.execute(
   31
       "modifyCluster",
   32
       projectID,
   33
       clusterName,
   34
       body
   35
     );
   36
     console.log(EJSON.stringify(result));
   37
   38
     return clusterName + " scaled up";
   39
   };

   将 <projectId> 和 <clusterName> 占位符替换为您自己的项目ID和集群名称，并根据您自己的拓扑结构调整 regionConfigs大量。

   请参阅“更新一个项目中的一个集群”端点文档，详细了解可以在请求正文中包含的用于修改集群配置的可用字段。

创建scaleClusterUp 定时触发器。

1. 在 Functions 页面中，单击 Build 标题下侧边栏中的 Triggers，导航到 Triggers 页面。

2. 单击 Create a Trigger 打开触发器配置页面。

   如果已有触发器，请单击 Add a Trigger

3. 配置触发器设置。

   在 Trigger Details 中，设立以下配置：

   设置	值
   触发器类型	預定
   进度表类型	高级。这允许您为安排指定 CRON表达式。 要每天早上在美国东部时间上午 8（即 13:00 UTC）运行此命令，请使用以下 CRON表达式： 0 13 * * *
   重新启用时跳过事件	打开。这可以防止触发器在禁用触发器时排队的计划上执行。
   eventType	函数。从下拉列表中选择 pauseClusters 函数。
   触发器名称	scaleClusterUp

4. 单击 Save 以创建触发器。

   现在，您的测试集群将在每天早上 8 AM 美国东部时间自动扩展。

创建scaleClusterDown 函数。

1. 将 scaleClusterUp 函数复制到名为 scaleClusterDown 的新函数中。

2. 在 Function Editor标签页中，粘贴并调整以下代码，将集群扩展到指定配置：

   1
   /*
   2
    * Scales a single cluster down to a smaller instance size.
   3
    * This example scales an AWS cluster down to M10 in region US_EAST_1.
   4
    */
   5
   exports = async function() {
   6
     const projectID   = "<projectId>";
   7
     const clusterName = "<clusterName>";
   8
   9
     const body = {
   10
       replicationSpecs: [
   11
         {
   12
           regionConfigs: [
   13
             {
   14
               electableSpecs: {
   15
                 instanceSize: "M10", // for example, smaller tier
   16
                 nodeCount: 3
   17
               },
   18
               priority:     7,
   19
               providerName: "AWS",
   20
               regionName:   "US_EAST_1"
   21
             }
   22
           ]
   23
         }
   24
       ]
   25
     };
   26
   27
     // Scale down the cluster and log the response
   28
     const result = await context.functions.execute(
   29
       "modifyCluster",
   30
       projectID,
   31
       clusterName,
   32
       body
   33
     );
   34
     console.log(EJSON.stringify(result));
   35
   36
     return clusterName + " scaled down";
   37
   };

   将 <projectId> 和 <clusterName> 占位符替换为您自己的项目ID和集群名称，并根据您自己的拓扑结构调整 regionConfigs大量。

   请参阅“更新一个项目中的一个集群”端点文档，详细了解可以在请求正文中包含的用于修改集群配置的可用字段。

创建scaleClusterDown 定时触发器。

1. 在 Functions 页面中，单击 Build 标题下侧边栏中的 Triggers，导航到 Triggers 页面。

2. 配置触发器设置。

   在 Trigger Details 中，设立以下配置：

   设置	值
   触发器类型	預定
   进度表类型	高级。这允许您为安排指定 CRON表达式。 要在每天晚上 6 PM 美国东部时间（即 22:00 UTC）运行此命令，请使用以下 CRON表达式： 0 22 * * *
   重新启用时跳过事件	打开。这可以防止触发器在禁用触发器时排队的计划上执行。
   eventType	函数。从下拉列表中选择 scaleClusterDown 函数。
   触发器名称	scaleClusterDown

3. 单击 Save 以创建触发器。

这两个触发器共同确保集群在繁忙时段以更高的容量运行，并在繁忙时段缩减规模。