> 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 Runbooks を使って環境内の日々の運用を自動化できます。参照: [Runbook](/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 がユーザーのメールボックスに eMail-Alias を追加する場合です。

各ジョブには、その現在の実行状態を表すステータスがあります。参照: [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 の命名

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`、 `ステータス` (`失敗` または `完了`）と 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` を使用して現在のステータスを問い合わせます。

参照 [認証 ](/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)

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

```
完了
```

その他の可能な状態には `新規`, `失敗`, `実行中`。参照: [可能な 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) は個別に処理されます。

参照 [認証 ](/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 表現で取得できます。これにより、 `出力`, `詳細` および `エラー` ストリームにアクセスできます。 [例外](#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": "詳細",
        "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": "詳細またはデバッグメッセージ",
        "streamType": "詳細",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.7672223+00:00",
        "summary": "中断しないエラーメッセージ",
        "streamType": "エラー",
        "streamText": null,
        "value": null
    }
]
```

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

たとえば Verbose のように単一のストリームだけを受け取りたい場合は、リクエストにフィルターを追加することで `?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
```

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

**レスポンス**

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

### 例外の読み取り

次を使用します `/runbook/jobs/{jobID}/exception/text` を使用すると、runbook の例外メッセージの簡単なプレーンテキスト表現を取得できます（存在する場合）。これには `出力`, `詳細` および `エラー` ストリームは含まれません。参照: [ストリームの読み取り](#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 dynamically by asking a question.

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

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.