ランブックでの条件文の使用 - AWS Systems Manager
aws:branch アクションの使用条件オプションの使用例

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

ランブックでの条件文の使用

デフォルトでは、ランブックの mainSteps セクションで定義したステップは順番に実行されます。1 つのアクションが完了した後、mainSteps セクションで指定された次のアクションが開始されます。さらに、アクションが失敗した場合は、(デフォルトでは) オートメーション全体の実行に失敗します。このセクションで説明されている aws:branch オートメーションアクションおよびランブックオプションを使用すると、条件付き分岐を実行するオートメーションを作成できます。つまり、異なる選択肢を評価した後に異なるステップにジャンプするオートメーションを作成したり、ステップが完了したときに変更に動的に応答するオートメーションを作成することができます。動的オートメーションの作成に使用できるオプションのリストは次のとおりです。

  • aws:branch: この自動化アクションを使用すると、1 つのステップで複数の選択肢を評価し、その評価結果に基づいてランブックの異なるステップにジャンプする動的オートメーションを作成できます。

  • nextStep: このオプションは、ステップを正常に完了した後に、次に処理するオートメーションのステップを指定します。

  • isEnd: このオプションでは、特定のステップの最後にオートメーションを停止します。このオプションのデフォルト値は false です。

  • isCritical: このオプションはオートメーションの正常な完了のために、ステップを critical として指定します。この指定のステップが失敗した場合、オートメーションはオートメーションの失敗の最終的なステータスを Failed としてレポートします。このオプションのデフォルト値は true です。

  • onFailure: このオプションは失敗時にオートメーションを中止するか、続行するか、または別のステップに移行するかを示します。このオプションのデフォルト値は中止です。

次のセクションでは、aws:branch オートメーションアクションについて説明します。nextStep、isEnd、isCritical、onFailure オプションの詳細については、「aws:branch ランブックの例」を参照してください。

aws:branch アクションの使用

aws:branch アクションは、オートメーションのための最も動的な条件分岐オプションを提供します。前述のとおり、このアクションによって、オートメーションで複数の条件を 1 つのステップで評価し、その評価の結果に基づいて新しいステップにジャンプすることができます。aws:branch アクションは、プログラミングで IF-ELIF-ELSE ステートメントのように機能します。

以下に、aws:branch ステップの YAML の例を示します。

- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

ステップの aws:branch アクションを指定する場合、オートメーションが評価する必要のある Choices を指定します。オートメーションは、ランブックの Choices セクションで指定したパラメータの値に基づいて、Parameters を評価できます。オートメーションは、前の手順の出力に基づいて Choices を評価することもできます。

自動化は、ブール式を使用して各選択肢を評価します。最初の選択肢が true であると判断された場合、オートメーションはその選択肢で指定されたステップにジャンプします。最初の選択肢が false であると判断された場合、オートメーションは次の選択肢を評価します。ステップに 3 つ以上の Choices が含まれている場合、オートメーションは、true である選択肢を評価するまで、各選択肢を順番に評価します。次に、オートメーションは、true の選択のために指定されたステップにジャンプします。

Choices である true がない場合、オートメーションはステップに Default 値が含まれているかどうかを確認します。Default 値は、true である選択肢がない場合にオートメーションがジャンプするステップを定義します。ステップに Default 値が指定されていない場合、オートメーションはランブックの次のステップを処理します。

以下は、chooseOSfromParameter という名前の YAML の aws:branch ステップです。ステップには、2 つの Choices が含まれています。 (NextStep: runWindowsCommand) および (NextStep: runLinuxCommand)。オートメーションは、これらの Choices を評価して、適切なオペレーティングシステムで実行するコマンドを決定します。各選択肢の Variable は、{{OSName}} を使用します。これは、ランブック作成者がランブックの Parameters セクションで定義したパラメータです。

mainSteps:
- name: chooseOSfromParameter
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OSName}}"
      StringEquals: Windows
    - NextStep: runLinuxCommand
      Variable: "{{OSName}}"
      StringEquals: Linux

以下は、chooseOSfromOutput という名前の YAML の aws:branch ステップです。ステップには、2 つの Choices が含まれています。 (NextStep: runPowerShellCommand) および (NextStep: runShellCommand)。オートメーションは、これらの Choices を評価して、適切なオペレーティングシステムで実行するコマンドを決定します。各選択肢の Variable は、{{GetInstance.platform}} を使用します。これは、ランブックの前のステップからの出力です。この例では Default というオプションも含まれています。オートメーションが両方の Choices を評価し 、どちらの選択肢も true である場合、オートメーションは PostProcessing というステップにジャンプします。

mainSteps:
- name: chooseOSfromOutput
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

ランブック aws:branch でのステップの作成

ランブック aws:branch でステップを作成するときは、オートメーションが次にジャンプするステップを決定するために評価するChoices を定義します。前述のように、Choices はブール式を使用して評価されます。各選択肢は、次のオプションを定義する必要があります。

  • NextStep: 指定された選択肢が の場合に処理するランブックの次のステップtrue。

  • 変数 : ランブックの Parametersセクションで定義されているパラメータの名前、 Variablesセクションで定義されている変数を指定するか、前のステップの出力オブジェクトを指定します。

    次の形式を使用して変数値を指定します。

    Variable: "{{variable name}}"

    次の形式を使用してパラメータ値を指定します。

    Variable: "{{parameter name}}"

    次の形式を使用して出力オブジェクト変数を指定します。

    Variable: "{{previousStepName.outputName}}"

    注記

    出力変数の作成については、次のセクション「出力変数の作成について」でさらに詳しく説明します。

  • Operation: StringEquals: Linux などの選択肢を評価するために使用される基準。aws:branch アクションは、次の操作をサポートします。

    文字列演算子

    • StringEquals

    • EqualsIgnoreCase

    • StartsWith

    • EndsWith

    • を含む

    数値演算子

    • NumericEquals

    • NumericGreater

    • NumericLesser

    • NumericGreaterOrEquals

    • NumericLesser

    • NumericLesserOrEquals

    ブール演算子

    • BooleanEquals

    重要

    ランブックを作成すると、システムはランブック内の各オペレーションを検証します。オペレーションがサポートされていない場合は、ランブックの作成時にエラーが返されます。

  • Default: Choices である true がない場合にオートメーションがジャンプするフォールバックステップを指定します。

    注記

    Default 値を指定しない場合は、isEnd オプションを指定できます。Choices である true がない場合、および Default 値が指定されていない場合は、オートメーションはステップの最後で停止します。

次のテンプレートを使用して、ランブックの aws:branch ステップを構築します。各リソースプレースホルダーの例をユーザー自身の情報に置き換えます。

YAML
mainSteps:
- name: step name
  action: aws:branch
  inputs:
    Choices:
    - NextStep: step to jump to if evaluation for this choice is true
      Variable: "{{parameter name or output from previous step}}"
      Operation type: Operation value
    - NextStep: step to jump to if evaluation for this choice is true
      Variable: "{{parameter name or output from previous step}}"
      Operation type: Operation value
    Default:
      step to jump to if all choices are false
JSON
{
   "mainSteps":[
      {
         "name":"a name for the step",
         "action":"aws:branch",
         "inputs":{
            "Choices":[
               {
                  "NextStep":"step to jump to if evaluation for this choice is true",
                  "Variable":"{{parameter name or output from previous step}}",
                  "Operation type":"Operation value"
               },
               {
                  "NextStep":"step to jump to if evaluation for this choice is true",
                  "Variable":"{{parameter name or output from previous step}}",
                  "Operation type":"Operation value"
               }
            ],
            "Default":"step to jump to if all choices are false"
         }
      }
   ]
}

出力変数の作成について

前のステップからの出力を参照する aws:branch 選択肢を作成するには、前のステップの名前と出力フィールドの名前を特定する必要があります。次に、以下の形式を使用して、ステップ名とフィールド名を結合します。

Variable: "{{previousStepName.outputName}}"

例えば、次の例の最初のステップは GetInstance という名前です。そして、outputs の下に、platform というフィールドがあります。2 番目のステップ (ChooseOSforCommands) では、作成者はプラットフォームフィールドからの出力を変数として参照しようとしています。変数を作成するには、ステップ名 (GetInstance) と出力フィールド名 (プラットフォーム) を組み合わせて を作成しますVariable: "{{GetInstance.platform}}"。

mainSteps:
- Name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
    Filters:
    - Key: InstanceIds
      Values: ["{{ InstanceId }}"]
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep

前のステップと出力から "Variable": "{{ describeInstance.Platform }}" を作成する方法例を示します。

- name: describeInstance
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: DescribeInstances
    InstanceIds:
    - "{{ InstanceId }}"
  outputs:
  - Name: Platform
    Selector: "$.Reservations[0].Instances[0].Platform"
    Type: String
  nextStep: branchOnInstancePlatform
- name: branchOnInstancePlatform
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runEC2RescueForWindows
      Variable: "{{ describeInstance.Platform }}"
      StringEquals: windows
    Default: runEC2RescueForLinux

aws:branch ランブックの例

以下に、aws:branch を使用するランブックの例をいくつか挙げます。

例 1: 出力変数で aws:branch を使用し、オペレーティングシステムの種類に基づいてコマンドを実行する

この例 (GetInstance) の最初の手順では、ランブック作成者は aws:executeAwsApi アクションを使用して、ssm DescribeInstanceInformation API オペレーションを呼び出します。作成者はこのアクションを使用して、インスタンスが使用しているオペレーティングシステムのタイプを判別します。aws:executeAwsApi アクションはインスタンス ID とプラットフォームタイプを出力します。

2 番目のステップ (ChooseOSforCommands) では、2 つの aws:branch (Choices) と (NextStep: runPowerShellCommand) を使用して NextStep: runShellCommand アクションを使用します。自動化は、前の手順 (Variable: "{{GetInstance.platform}}") の出力を使用して、インスタンスのオペレーティングシステムを評価します。オートメーションは、指定されたオペレーティングシステムのステップにジャンプします。

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
mainSteps:
- name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep
- name: runShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runPowerShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunPowerShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

例 2: パラメータ変数で aws:branch を使用し、オペレーティングシステムの種類に基づいてコマンドを実行する

ランブック作成者は、parameters セクションのランブックの先頭にいくつかのパラメータオプションを定義します。1 つのパラメータの名前は OperatingSystemName です。最初のステップ (ChooseOS) では、2 つの aws:branch (Choices) と (NextStep: runWindowsCommand) を使用して NextStep: runLinuxCommand アクションを使用します。これらの Choices の変数は、パラメータセクション (Variable: "{{OperatingSystemName}}") で指定されたパラメータオプションを参照します。ユーザーがこのランブックを実行すると、実行時に OperatingSystemName の値を指定します 。オートメーションでは、Choices の評価時にランタイムパラメータが使用されます。オートメーションは、OperatingSystemName に指定されたランタイムパラメータに基づいて、指定されたオペレーティングシステムのステップにジャンプします。

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
  OperatingSystemName:
    type: String
  LinuxInstanceId:
    type: String
  WindowsInstanceId:
    type: String
mainSteps:
- name: ChooseOS
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: windows
    - NextStep: runLinuxCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: linux
    Default:
      Sleep
- name: runLinuxCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunShellScript"
    InstanceIds:
    - "{{LinuxInstanceId}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runWindowsCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunPowerShellScript"
    InstanceIds:
    - "{{WindowsInstanceId}}"
    Parameters:
      commands:
      - date
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

演算子を使用した複雑な分岐オートメーションの作成

And ステップで Or、Not、および aws:branch 演算子を使用して、複雑な分岐オートメーションを作成できます。

"And" 演算子

選択肢の複数の変数を And にする場合は、true 演算子を使用します。次の例では、最初の選択肢に対して、インスタンスが running の状態で、Windows オペレーティングシステムを使用しているかどうかを評価します。これらの変数の両方が true と評価された場合、オートメーションは runPowerShellCommand ステップにジャンプします。1 つ以上の変数が false の場合、オートメーションは 2 番目の選択肢の変数を評価します。

mainSteps:
- name: switch2
  action: aws:branch
  inputs:
    Choices:
    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Windows
      NextStep: runPowerShellCommand

    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Linux
      NextStep: runShellCommand
    Default:
      sleep3
"OR" 演算子

選択肢の複数の変数のいずれかを true にする場合は、Or 演算子を使用します。次の例では、最初の選択は、パラメータ文字列が Windows であるかどうか、 AWS Lambda ステップからの出力が true かどうかを評価します。これらの変数のどちらかが true であると判断された場合、オートメーションは RunPowerShellCommand ステップにジャンプします。両方の変数が false の場合、オートメーションは 2 番目の選択肢の変数を評価します。

- Or:
  - Variable: "{{parameter1}}"
    StringEquals: Windows
  - Variable: "{{BooleanParam1}}"
    BooleanEquals: true
  NextStep: RunPowershellCommand
- Or:
  - Variable: "{{parameter2}}"
    StringEquals: Linux
  - Variable: "{{BooleanParam2}}"
    BooleanEquals: true
  NextStep: RunShellScript
"Not" 演算子

変数が true でない場合に定義されたステップにジャンプする場合は、Not 演算子を使用します。次の例では、最初の選択肢は、パラメータ文字列が Not Linux かどうかを評価します。変数が Linux ではないと判断された場合、オートメーションは sleep2 ステップにジャンプします。最初の選択肢が Linux であると判断された場合、オートメーションは次の選択肢を評価します。

mainSteps:
- name: switch
  action: aws:branch
  inputs:
    Choices:
    - NextStep: sleep2
      Not:
        Variable: "{{testParam}}"
        StringEquals: Linux
    - NextStep: sleep1
      Variable: "{{testParam}}"
      StringEquals: Windows
    Default:
      sleep3

条件オプションの使用例

このセクションでは、ランブックで動的オプションを使用するさまざまな例について説明します。このセクションのそれぞれの例では、次のランブックを拡張します。このランブックには 2 つのアクションがあります。最初のアクションは InstallMsiPackage という名前です。aws:runCommand アクションを使用して、Windows Server インスタンスにアプリケーションをインストールします。2 番目のアクションは、TestInstall という名前です。このアクションは、aws:invokeLambdaFunction アクションを使用し、アプリケーションが正常にインストールされているかどうか、インストールされているアプリケーションのテストを実行します。ステップ 1 で onFailure: Abort を指定します。つまり、アプリケーションがインストールされなかった場合は、オートメーションの実行はステップ 2 より前で停止します。

例 1:2 つのリニアアクションがあるランブック

---
schemaVersion: '0.3'
description: Install MSI package and run validation.
assumeRole: "{{automationAssumeRole}}"
parameters:
  automationAssumeRole:
    type: String
    description: "(Required) Assume role."
  packageName:
    type: String
    description: "(Required) MSI package to be installed."
  instanceIds:
    type: String
    description: "(Required) Comma separated list of instances."
mainSteps:
- name: InstallMsiPackage
  action: aws:runCommand
  maxAttempts: 2
  onFailure: Abort
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
...

onFailure オプションを使用し、別のステップにジャンプする動的オートメーションを作成する

次の例では、onFailure: step:step name、nextStep、および isEnd オプションを使用して、動的オートメーションを作成します。この例では、 InstallMsiPackageアクションが失敗した場合、オートメーションは PostFailure (onFailure: step:PostFailure) というアクションにジャンプし、 AWS Lambda 関数を実行して、インストールが失敗したイベントで何らかのアクションを実行します。インストールが成功すると、オートメーションは TestInstall アクション () にジャンプしますnextStep: TestInstall。TestInstall ステップと PostFailure ステップの両方で isEnd オプション (isEnd: true) を使用すると、これらのステップのいずれかが完了したときにオートメーションが終了します。

注記

isEnd セクションの最後のステップでの、mainSteps オプションの使用はオプションです。最後のステップが他のステップにジャンプしない場合、最後のステップのアクションの実行後にオートメーションは停止します。

例 2: 別のステップにジャンプする動的オートメーション

mainSteps
- name: InstallMsiPackage
  action: aws:runCommand
  onFailure: step:PostFailure
  maxAttempts: 2
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
  nextStep: TestInstall
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
  isEnd: true
- name: PostFailure
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: PostFailureRecoveryLambdaFunction
  isEnd: true
...
注記

ランブックを処理する前に、システムはランブックが無限ループを作成していないことを確認します。無限ループが検出された場合、自動化はエラー、およびどのステップがループを作成しているかを示すサークルトレースを返します。

重要な手順を定義する動的オートメーションの作成

オートメーション全体の成功にとって非常に重要なステップを指定できます。重要なステップが失敗した場合、1 つ以上のステップが正常に実行されたとしても、オートメーションは実行のステータスを Failed としてレポートします。次の例では、VerifyDependenciesステップが失敗した場合 ()、ユーザーはInstallMsiPackageステップを識別しますonFailure: step:VerifyDependencies。ユーザーは、InstallMsiPackage ステップが critical ではないことを指定します (isCritical: false)。この例では、アプリケーションのインストールに失敗した場合、自動化は VerifyDependencies ステップを処理して、アプリケーションのインストールが失敗する原因となる、1 つ以上の依存関係が欠落していないかどうかを判断します。

例 3: オートメーションを定義する重要なステップ

---
name: InstallMsiPackage
action: aws:runCommand
onFailure: step:VerifyDependencies
isCritical: false
maxAttempts: 2
inputs:
  InstanceIds:
  - "{{instanceIds}}"
  DocumentName: AWS-RunPowerShellScript
  Parameters:
    commands:
    - msiexec /i {{packageName}}
nextStep: TestPackage
...