# Runbookの操作

## 概要

RealmJoin を使用すると、Azure Automation Runbook を使って環境内の日々の運用を自動化できます。参照してください [Runbooks](/ja/zi-dong-hua/runbooks.md) をご覧ください。

RealmJoin の API を使うと、アプリケーションから runbook を開始したり、以前にトリガーされた実行の正常終了を問い合わせたりできます。参照してください [RealmJoin の Swagger 説明](https://customer-api.realmjoin.com/swagger/index.html) 現在どの操作がサポートされているかを確認してください。

以下のセクションでは、RealmJoin の API を使って runbook ジョブを開始し、追跡する方法を説明します。すでに [Azure Automation アカウントを接続している](/ja/zi-dong-hua/connecting-azure-automation.md) ことを前提としています。また、 [認証する ](/ja/dev-reference/realmjoin-api/authentication.md)適切な HTTP Authorization ヘッダーを使用して、RealmJoin の API に対するすべてのリクエストを。

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

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

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

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

各ジョブには、その現在の実行状態を表すステータスがあります。参照してください [Microsoft Docs](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses)。ここでは `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`

参照 [命名規則](/ja/zi-dong-hua/runbooks/naming-conventions.md) をご覧ください。

### 例

次の状況を想定しましょう。

* RealmJoin の API 資格情報を持っており、それを次のようにエンコードしました `dC0xMjM0MTIzNDpteVMzY3JldCE=` (Base64)
* 次の runbook を開始したいとします `rjgit-user_security_revoke-or-restore-access` 特定のユーザーのサインインをブロックするための
* runbook（PowerShell）のパラメーターは次のとおりです。
  * `$UserName = "someone@contoso.com"`
  * `$Revoke = $true`

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

次を作成してみましょう。 **要求**:

ヘッダー:

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

リクエスト / URI:

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

ボディ（JSON表記）:

```json
{ 
   "UserName": "someone@contoso.com", 
   "Revoke": true 
}
```

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

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

**レスポンス**:

HTTP ステータス: `200` (OK)

ボディ（JSON表記）:

```json
{
    "jobID": "1234545e-7a24-436a-90c9-6056b512345",
    "status": "Completed",
    "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 が終了した後、次の` エンドポイントを使用してこれらのストリームを取得できます。

## ジョブのステータスと出力の問い合わせ

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

### ジョブステータスの問い合わせ

使用してください `/runbook/jobs/{jobID}/status` で現在のステータスを問い合わせます。

参照 [認証 ](/ja/dev-reference/realmjoin-api/authentication.md)Authorization ヘッダーの作成方法については、以下はあくまで例です。

次の `jobID` を `1234545e-7a24-436a-90c9-6056b512345`

**`リクエスト`**

ヘッダー:

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

リクエスト / URI:

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

このリクエストには body はありません。

**レスポンス**

Http Status 200 (OK)

Body (Plaintext)

```
Completed
```

他に考えられる状態には `New`, `Failed`, `Running`があります。参照してください [可能な Runbook の状態](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses).

### ジョブ出力の読み取り

使用してください `/runbook/jobs/{jobID}/output/text` を使用して、runbook の出力をシンプルなプレーンテキスト形式で取得します。これには `Verbose` と `Error` stream [は含まれません。その他のストリームを読み取るには](#reading-specific-streams) ストリームの読み取り [例外](#reading-exceptions) は個別に扱われます。

参照 [認証 ](/ja/dev-reference/realmjoin-api/authentication.md)Authorization ヘッダーの作成方法については、以下はあくまで例です。

次の `jobID` を `1234545e-7a24-436a-90c9-6056b512345`

**リクエスト**

ヘッダー:

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

リクエスト / URI:

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

このリクエストには body はありません。

**レスポンス**

Http Status 200 (OK)

Body (Plaintext)

```
## 配布グループ 'Sales Team' が作成されました。
```

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

使用してください `runbook が終了した後、次の` を使用して、runbook の出力を包括的な JSON 形式で取得します。これにより、 `出力`, `Verbose` と `Error` stream [例外](#reading-exceptions) は個別に扱われます。

参照 [認証 ](/ja/dev-reference/realmjoin-api/authentication.md)Authorization ヘッダーの作成方法については、以下はあくまで例です。

次の `jobID` を `1234545e-7a24-436a-90c9-6056b512345`

**要求（すべてのストリーム）**

ヘッダー:

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

リクエスト / URI:

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

このリクエストには body はありません。

**レスポンス**

Http Status 200 (OK)

Body (JSON, メッセージの配列)

```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": "Verbose または Debug メッセージ",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "処理を中断しないエラーメッセージ",
        "streamType": "Error",
        "streamText": null,
        "value": null
    }
]
```

中断を伴うエラーメッセージと [例外](#reading-exceptions)

を読み取るには、以下を参照してください。たとえば Verbose のように単一のストリームだけを受け取りたい場合は、 `?streamTypes=Verbose`を追加してリクエストにフィルターを加えることができます。また、 `出力` と `Error`.

**単一のストリームでフィルターする要求**

ヘッダー:

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

リクエスト / URI:

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

このリクエストには body はありません。

**レスポンス**

Http Status 200 (OK)

Body (JSON, メッセージの配列)

```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": "Verbose または Debug メッセージ",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    }
]
```

### 例外の読み取り

使用してください `/runbook/jobs/{jobID}/exception/text` を使用して、runbook の例外メッセージをシンプルなプレーンテキスト形式で取得します（存在する場合）。これには `出力`, `Verbose` と `Error` streams [は含まれません。その他のストリームを読み取るには](#reading-specific-streams) ストリームの読み取り

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

この例では、中断を伴うエラーは `throw "Exception"`.

参照 [認証 ](/ja/dev-reference/realmjoin-api/authentication.md)Authorization ヘッダーの作成方法については、以下はあくまで例です。

次の `jobID` を `1234545e-7a24-436a-90c9-6056b512345`

**リクエスト**

ヘッダー:

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

リクエスト / URI:

```html
によって引き起こされました
```

このリクエストには body はありません。

**レスポンス**

Http Status 200 (OK)

Body (Plaintext)

```
Exception (Exception)
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.realmjoin.com/ja/dev-reference/interacting-with-runbooks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.