Runbook とのやり取り

RealmJoin の API を使用して Runbook を実行し、ステータスを照会します

概要

RealmJoin を使用すると、Azure Automation Runbooks を使用して環境の日常操作を自動化できます。詳しくは Runbooks を参照してください。

RealmJoin の API を使用すると、アプリケーションから Runbook を開始したり、以前にトリガーされた実行の成功を照会したりできます。詳しくは RealmJoin の Swagger 説明どの操作が現在サポートされているかを確認してください。

以下のセクションでは、RealmJoin の API を使用して Runbook ジョブを開始および追跡する方法を説明します。既に Azure Automation アカウントを接続していることが前提です RealmJoin ポータルに。また、次の点を確認してください認証適切な HTTP Authorization ヘッダーを使用して、RealmJoin の API に対するすべてのリクエストを認証してください。

Azure Automation は Runbook をどのように処理しますか？

Azure Automation は Runbook に関してバッチ処理アプローチを採用しています。Runbook の実行をトリガーすると、その Runbook のジョブが作成され、実行のためにキューに入れられます。

そのため一般に、Runbook はすぐに開始されません。同じ Runbook に対して複数のジョブが異なる実行状態で同時に存在することもあります。

各ジョブには Runbook スクリプトに渡される一連のパラメーター（入力）が含まれます。例えば、2つの変数のようなものです UPNが欲しい場合は、 同じ Log Analytics アカウントを $newEmailAddress もし Runbook がユーザーのメールボックスにメールエイリアスを追加することを想定している場合。

各ジョブにはその現在の実行状態を表すステータスがあり、詳細は次を参照してください Microsoft Docs。ここでは次に焦点を当てます キュー済み (Queued), 実行中 (Running), 完了 (Completed) 同じ Log Analytics アカウントを 失敗 (Failed) このドキュメントでは。これは理解を容易にするための単純化であることに注意してください。

Runbook ジョブの開始

RealmJoin API は Runbook をトリガーするための 2 つのエンドポイントを提供します。

run は Runbook を同期的に実行し、Runbook が実際に完了または失敗するまで返さず/終了しません。このエンドポイントは関連する Runbook ジョブの成功状態と出力を直接返します。

start は run と同じパラメーターを受け取りますが、非同期方式で動作します。Runbook ジョブがキューに入れられるとすぐに返します。返されるのは jobID で、新しいジョブの追跡を容易にします。

Runbook の命名

Runbook は Azure Automation の名前で参照されます。要約すると：

RealmJoin の GitHub リポジトリから同期されている場合は、プレフィックスとして rjgit-を追加します
次のいずれかを使用します org_, device_, group_, user_ をスコープとして使用します（これらのうち正確に一つ）
カテゴリ、例えば general_または security_
Runbook の名前（区切りは） _ のように add-xyz-exception

この場合の結果は次のようになります： rjgit-org_security_add-xyz-exception

参照：命名規則を参照してください。

例

次のような状況を仮定します：

RealmJoin の API 資格情報を取得し、それを dC0xMjM0MTIzNDpteVMzY3JldCE= にエンコードしました（Base64）
次の Runbook を開始したいとします rjgit-user_security_revoke-or-restore-access 特定のユーザーのサインインをブロックするために
Runbook（PowerShell）用のパラメーターは次のとおりです：
- $UserName = "[email protected]"
- $Revoke = $true

私たちは run エンドポイントを使用して、ジョブが成功したかどうかを即座に確認します。

では、次を構築してみましょう リクエスト:

ヘッダー：

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

リクエスト / URI：

POST https://customer-api.realmjoin.com/runbook/rjgit-user_security_revoke-or-restore-access/run

ボディ（JSON 表記）：

{ 
   "UserName": "[email protected]", 
   "Revoke": true 
}

このリクエストはジョブの実行を待つためしばらく時間がかかります。HTTP クライアントのタイムアウトを適切に調整してください。そうでない場合は、即座に返す start エンドポイントの使用を検討してください。

レスポンスには jobID、 status (失敗 (Failed) または 完了 (Completed)）と Runbook のすべての出力ストリームが含まれます。

レスポンス:

HTTP ステータス： 200 （OK）

ボディ（JSON 表記）：

{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Completed",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Running in Azure Automation account",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: Getting automation connection 'AzureRunAsConnection'",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: Connecting with AzureAD module: ...",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## User access for [email protected] has been revoked.",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}

出力ストリームは異なるチャネル（streamTypes): Output, Verbose, Error）に分けられます。これにより、エラーのみでフィルタリングしたり、関連情報だけを表示することで出力を減らしたりできます（例えば Output.

Runbook が終了した後、これらのストリームを次のエンドポイントで取得できます /runbook/jobs/{jobID}/output/streams （下記参照）

ジョブのステータスと出力の照会

ジョブが既に作成されている場合、RealmJoin API を使用してその状態と出力を照会できます。

ジョブステータスの照会

を使用して /runbook/jobs/{jobID}/status で現在のステータスを照会します。

参照：認証 Authorization ヘッダーの作成方法についてはを参照してください。以下はあくまで例です。

次の値を仮定します jobID が 1234545e-7a24-436a-90c9-6056b512345

リクエスト

ヘッダー：

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

リクエスト / URI：

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/status

このリクエストにボディはありません。

レスポンス

HTTP ステータス 200 (OK)

本文（プレーンテキスト）

完了 (Completed)

その他の可能な状態には次が含まれます New, 失敗 (Failed), 実行中 (Running)。詳しくは次を参照してください可能な Runbook 状態.

ジョブ出力の読み取り

を使用して /runbook/jobs/{jobID}/output/text で Runbook の出力のシンプルなプレーンテキスト表現を取得できます。これは Verbose 同じ Log Analytics アカウントを Error ストリームを含みません。詳しくはストリームの読み取りで他のストリームを読み取ってください。例外は別途扱われます。

参照：認証 Authorization ヘッダーの作成方法についてはを参照してください。以下はあくまで例です。

次の値を仮定します jobID が 1234545e-7a24-436a-90c9-6056b512345

リクエスト

ヘッダー：

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

リクエスト / URI：

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/text

このリクエストにボディはありません。

レスポンス

HTTP ステータス 200 (OK)

本文（プレーンテキスト）

## ディストリビューショングループ 'Sales Team' が作成されました。

特定のストリームの読み取り

を使用して /runbook/jobs/{jobID}/output/streams で Runbook の出力の包括的な JSON 表現を取得できます。これにより Output, Verbose 同じ Log Analytics アカウントを Error ストリームにアクセスできます。例外は別途扱われます。

参照：認証 Authorization ヘッダーの作成方法についてはを参照してください。以下はあくまで例です。

次の値を仮定します jobID が 1234545e-7a24-436a-90c9-6056b512345

リクエスト（全ストリーム）

ヘッダー：

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

リクエスト / URI：

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams

このリクエストにボディはありません。

レスポンス

HTTP ステータス 200 (OK)

本文（JSON、メッセージの配列）

[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Running in Azure Automation account",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "Regular Output",
        "streamType": "Output",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Verbose or Debug Message",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "Non-interrupting Error Message",
        "streamType": "Error",
        "streamText": null,
        "value": null
    }
]

割り込みを伴うエラーメッセージおよび次の項目を読む方法については下記を参照してください例外

単一のストリーム（例えば Verbose）だけを受け取るには、リクエストに次を追加してフィルターを付けることができます ?streamTypes=Verbose。また、次でフィルタリングすることもできます Output 同じ Log Analytics アカウントを Error.

リクエスト（単一ストリームでフィルタリング）

ヘッダー：

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

リクエスト / URI：

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams?streamTypes=Verbose

このリクエストにボディはありません。

レスポンス

HTTP ステータス 200 (OK)

本文（JSON、メッセージの配列）

[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "Loading module from path 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1'.",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Running in Azure Automation account",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Verbose or Debug Message",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]

例外の読み取り

を使用して /runbook/jobs/{jobID}/exception/text で Runbook の例外メッセージ（存在する場合）のシンプルなプレーンテキスト表現を取得できます。これは Output, Verbose 同じ Log Analytics アカウントを Error ストリームを含みません。詳しくはストリームの読み取りで他のストリームを読み取ってください。

例外は、Runbook に関連付けられた PowerShell スクリプトの実行中に割り込みエラーが発生したときに書き込まれます。このエンドポイントはプレーンテキストのメッセージのみを読み取り、スクリプトがどの行で停止したかのような技術的な詳細は含みません。

この例では、割り込みエラーは次によって引き起こされました throw "Exception".

参照：認証 Authorization ヘッダーの作成方法についてはを参照してください。以下はあくまで例です。

次の値を仮定します jobID が 1234545e-7a24-436a-90c9-6056b512345

リクエスト

ヘッダー：

Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json

リクエスト / URI：

GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/exception/text

このリクエストにボディはありません。

レスポンス

HTTP ステータス 200 (OK)

本文（プレーンテキスト）

Exception (Exception)

最終更新 11 か月前

役に立ちましたか？

こんにちは

hashtag概要

hashtagAzure Automation は Runbook をどのように処理しますか？

hashtagRunbook ジョブの開始

hashtagRunbook の命名

hashtag例

hashtagジョブのステータスと出力の照会

hashtagジョブステータスの照会

hashtagジョブ出力の読み取り

hashtag特定のストリームの読み取り

hashtag例外の読み取り

概要

Azure Automation は Runbook をどのように処理しますか？

Runbook ジョブの開始

Runbook の命名

例

ジョブのステータスと出力の照会

ジョブステータスの照会

ジョブ出力の読み取り

特定のストリームの読み取り

例外の読み取り