> 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 を使うと、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) RealmJoin Portal に接続済みであること。また、必ず [認証してください ](/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 の完了後に、これらのストリームを次の `/runbook/jobs/{jobID}/output/streams` エンドポイントで取得できます。（下記参照）

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

ジョブがすでに作成されている場合、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 表現で取得できます。これにより、 `出力`, `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 またはデバッグ メッセージ",
        "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 のような 1 つのストリームだけを受け取りたい場合は、次を追加してリクエストにフィルターを追加できます `?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
```

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

**レスポンス**

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

### 例外の読み取り

使用: `/runbook/jobs/{jobID}/exception/text` を使用すると、runbook の例外メッセージ（存在する場合）をシンプルなプレーンテキストで取得できます。これには `出力`, `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 (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 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.