> 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).

# Runbooks との連携

## 概要

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 がユーザーのメールボックスに 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 のように 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
```

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

**応答**

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.