> 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 を使用して、環境内の日常業務を自動化できます。参照してください [Runbooks](https://docs.realmjoin.com/ja/zi-dong-hua/runbooks.md) をご覧ください。

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

以下のセクションでは、RealmJoin の API を使用して Runbook ジョブを開始および追跡する方法を説明します。すでに [Azure Automation アカウントを接続していることを前提としています](https://docs.realmjoin.com/ja/zi-dong-hua/connecting-azure-automation.md) RealmJoin Portal に接続済みであること。また、 [認証する ](https://docs.realmjoin.com/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)。ここでは次に焦点を当てます `キュー済み`, `実行中`, `完了` と `失敗` をこの文書で扱います。これは理解しやすくするための簡略化であることに注意してください。

## Runbook ジョブの開始

RealmJoin API には Runbook をトリガーする 2 つのエンドポイントがあります。

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

`start` は次と同じパラメーターを受け取ります `run` ただし、非同期で動作します。Runbook ジョブがキューに入るとすぐに返却されます。返されるのは `jobID` 新しいジョブを簡単に追跡するためのものです。

### Runbook の命名

Azure Automation では Runbook は名前で指定されます。要するに:

* RealmJoin の GitHub リポジトリから同期されている場合は、 `rjgit-`接頭辞として追加します
* いずれか `org_`, `device_`, `group_`, `user_` をスコープとして使用します（これらのうちちょうど 1 つ）。
* 次のようなカテゴリです `general_`または `security_`
* 区切り記号で区切られた Runbook 名です `_` 例: `add-xyz-exception`

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

参照 [命名規則](https://docs.realmjoin.com/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`、 `ステータス` (`失敗` または `完了`）と Runbook のすべての出力ストリームです。

**レスポンス**:

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

本文（JSON 表記）:

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

出力ストリームは異なるチャネル（`streamTypes`): `出力`, `詳細`, `エラー`。これにより、エラーを絞り込んだり、必要な情報だけを表示することで出力を削減したりできます。 `出力`.

Runbook の完了後に、次のものを使用してこれらのストリームを取得できます `/runbook/jobs/{jobID}/output/streams` エンドポイントです（以下参照）。

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

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

### ジョブのステータスを照会

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

参照 [認証 ](https://docs.realmjoin.com/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 ステータス 200（OK）

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

```
完了
```

その他の可能な状態には次が含まれます `新規`, `失敗`, `実行中`。こちらも参照してください [Runbook の可能な状態](https://docs.microsoft.com/en-us/azure/automation/automation-runbook-execution#job-statuses).

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

使用してください `/runbook/jobs/{jobID}/output/text` Runbook の出力をシンプルなプレーンテキスト形式で取得するためのものです。これには次のものは含まれません `詳細` と `エラー` ストリーム。参照 [ストリームの読み取り](#reading-specific-streams) 他のストリームを読み取るには [例外](#reading-exceptions) は別々に処理されます。

参照 [認証 ](https://docs.realmjoin.com/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 ステータス 200（OK）

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

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

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

使用してください `/runbook/jobs/{jobID}/output/streams` Runbook の出力を包括的な JSON 表現で取得するためのものです。これにより、次のものにアクセスできます `出力`, `詳細` と `エラー` ストリーム。 [例外](#reading-exceptions) は別々に処理されます。

参照 [認証 ](https://docs.realmjoin.com/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 ステータス 200（OK）

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

```json
[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "パス 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' からモジュールを読み込み中。",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "パス 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1' からモジュールを読み込み中。",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Azure Automation アカウントで実行中",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.3122219+00:00",
        "summary": "通常の出力",
        "streamType": "出力",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Verbose または Debug メッセージ",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "中断しないエラーメッセージ",
        "streamType": "エラー",
        "streamText": null,
        "value": null
    }
]
```

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

たとえば Verbose のように 1 つのストリームだけを受け取るには、次を追加してリクエストにフィルターを追加できます `?streamTypes=Verbose`。次の条件でもフィルタリングできます `出力` と `エラー`.

**リクエスト（単一ストリームのフィルタ）**

ヘッダー:

```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 ステータス 200（OK）

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

```json
[
    {
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "summary": "パス 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' からモジュールを読み込み中。",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "summary": "パス 'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1' からモジュールを読み込み中。",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+00:00",
        "summary": "RealmJoin.RunbookHelper: Azure Automation アカウントで実行中",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.8422225+00:00",
        "summary": "Verbose または Debug メッセージ",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    }
]
```

### 例外の読み取り

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

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

この例では、中断を伴うエラーは次によって発生しました `throw "Exception"`.

参照 [認証 ](https://docs.realmjoin.com/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
```

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

**レスポンス**

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.
