> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/ja/dev-reference/interacting-with-runbooks.md).

# Runbook の操作

RealmJoin の API を使用して runbook を実行し、その状態を照会します

## 概要

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

RealmJoin の API を使用すると、アプリケーションから Runbook を開始したり、以前にトリガーされた実行の成功を問い合わせたりできます。詳細は [RealmJoin の API リファレンス](https://customer-api.realmjoin.com/scalar/v1) を参照して、現在サポートされている操作を確認してください。

以下のセクションでは、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 スクリプトに渡されるパラメーター（入力）のセットがあります。たとえば、 `$username` と `$newEmailAddress` のような 2 つの変数になることがあります。これは、Runbook がユーザーのメールボックスに eMail-Alias を追加する場合などです。

各ジョブには現在の実行状態を表すステータスがあります。詳細は [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_`
* のようなカテゴリ、 `_` のように `add-xyz-exception`

Runbook 名を `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`、 `ステータス` (`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`): `Output`, `Verbose`, `Error`）に分かれています。これにより、 `Output`.

だけを表示して、エラーをフィルタリングしたり、出力を関連情報のみに絞ったりできます。 `/runbook/jobs/{jobID}/output/streams` エンドポイントを使って、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
```

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

**レスポンス**

Http ステータス 200 (OK)

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

```
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` ストリームは含まれません。詳細は [ストリームの読み取り](#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
```

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

**レスポンス**

Http ステータス 200 (OK)

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

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

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

使用 `/runbook/jobs/{jobID}/output/streams` を使用して、Runbook の出力を包括的な JSON 表現で取得します。これにより、 `Output`, `Verbose` と `Error` ストリームにアクセスできます。 [例外](#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
```

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

**レスポンス**

Http ステータス 200 (OK)

本文（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`を追加してリクエストにフィルターを加えることができます。さらに `Output` と `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
```

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

**レスポンス**

Http ステータス 200 (OK)

本文（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 の例外メッセージをシンプルなプレーンテキストで取得します（存在する場合）。これには `Output`, `Verbose` と `Error` ストリームは含まれません。詳細は [ストリームの読み取り](#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
GET https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/exception/text
```

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

**レスポンス**

Http ステータス 200 (OK)

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

```
例外 (Exception)
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.