Runbook の操作

RealmJoins API を使用して Runbook を実行し、その状態を照会する

概要

RealmJoin を使用すると、Azure Automation Runbook を使って、環境内の日常的な運用を自動化できます。参照 Runbooks 詳細については。

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

以下のセクションでは、RealmJoin の API を使用して runbook ジョブを開始し追跡する方法を説明します。すでに次を行っていることを前提としています Azure Automation アカウントを接続済みしていること。また、次も必ず認証する際には、適切な http Authorization ヘッダーを使って RealmJoin の API への各リクエストを行ってください。

Azure Automation は runbook をどのように扱いますか?

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

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

各ジョブには、runbook スクリプトに渡されるパラメーター（入力）のセットがあります。たとえば、次のような 2 つの変数です $username および $newEmailAddress runbook がユーザーのメールボックスに eMail-Alias を追加する場合。

各ジョブには、現在の実行状態を表すステータスがあります。参照 Microsoft Docs。ここでは次に焦点を当てます Queued, Running, Completed および 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_ をスコープとして（これらのうちちょうど 1 つ）
カテゴリ。たとえば 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 = "someone@contoso.com"
- $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": "someone@contoso.com", 
   "Revoke": true 
}

ジョブの実行を待機するため、このリクエストには時間がかかります。http クライアントのタイムアウトをそれに合わせて調整してください。そうでない場合は、次を使用してみてください start エンドポイントは、すぐに応答を返します。

レスポンスには次が含まれます jobID、 ステータス (Failed または Completed) と runbook のすべての出力ストリームです。

レスポンス:

Http Status: 200 （OK）

本文（JSON 表記）:

{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "完了",
    "streams": [
        {
            "time": "2021-12-15T14:47:27.7756185+00:00",
            "summary": "RealmJoin.RunbookHelper: Azure Automation アカウントで実行中",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:27.96063+00:00",
            "summary": "getAutomationConnectionOrFromLocalCertificate: 自動化接続 'AzureRunAsConnection' を取得中",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:31.560861+00:00",
            "summary": "Connect-RjRbAzureAD: AzureAD モジュールで接続中: ...",
            "streamType": "Verbose",
            "streamText": null,
            "value": null
        },
        {
            "time": "2021-12-15T14:47:33.8860333+00:00",
            "summary": "## someone@contoso.com のユーザーアクセスは取り消されました。",
            "streamType": "Output",
            "streamText": null,
            "value": null
        }
    ]
}

出力ストリームは、異なるチャネル（streamTypes): 出力, Verbose, Error。これにより、エラーでフィルタリングしたり、 出力.

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

他に考えられる状態には次が含まれます 新規, Failed, Running。参照考えられる Runbook の状態.

ジョブ出力の読み取り

使用してください /runbook/jobs/{jobID}/output/text runbook の出力を簡単なプレーンテキスト表現で取得します。これには Verbose および 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 表現で取得します。これにより、 出力, Verbose および 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": "パス 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' からモジュールを読み込み中。",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "パス '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: Azure Automation アカウントで実行中",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "通常の出力",
        "streamType": "Output",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "詳細またはデバッグ メッセージ",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "中断しないエラー メッセージ",
        "streamType": "エラー",
        "streamText": null,
        "value": null
    }
]

中断を伴うエラーメッセージと例外

たとえば Verbose のように 1 つのストリームだけを受け取りたい場合は、次を追加してリクエストにフィルターを追加できます ?streamTypes=Verbose。さらに、次でもフィルターできます 出力 および 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": "パス 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' からモジュールを読み込み中。",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "パス '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: Azure Automation アカウントで実行中",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "詳細またはデバッグ メッセージ",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]

例外の読み取り

使用してください /runbook/jobs/{jobID}/exception/text runbook の例外メッセージ（存在する場合）の簡単なプレーンテキスト表現を取得します。これには 出力, Verbose および 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）

最終更新 27 日前

役に立ちましたか？