# Runbook とのやり取り

## 概要

RealmJoin を使用すると、Azure Automation Runbook を利用して、環境内の日常業務を自動化できます。参照してください [Runbooks](https://docs.realmjoin.com/ja/zi-dong-hua/runbooks) 詳細については、こちらを参照してください。

RealmJoin の API を使用すると、アプリケーションから runbook を開始し、以前にトリガーされた実行の正常な完了を照会できます。参照してください [RealmJoin の Swagger の説明](https://customer-api.realmjoin.com/swagger/index.html) どの操作が現在サポートされているかを確認するために。

以下のセクションでは、RealmJoin の API を使用して runbook ジョブを開始および追跡する方法を説明します。すでに [Azure Automation アカウントを接続済みである](https://docs.realmjoin.com/ja/zi-dong-hua/connecting-azure-automation) RealmJoin Portal に。さらに、必ず [認証 ](https://docs.realmjoin.com/ja/dev-reference/realmjoin-api/authentication)を適切な 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). ここでは `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`

 参照 [命名規則](https://docs.realmjoin.com/ja/zi-dong-hua/runbooks/naming-conventions) 詳細については

### 例

次の状況を想定しましょう:

* 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: automation 接続 '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` を使用して現在のステータスを照会します。

参照 [認証 ](https://docs.realmjoin.com/ja/dev-reference/realmjoin-api/authentication)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 Status 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` stream [は含まれません。その他のストリームを読み取るには](#reading-specific-streams) ストリームの読み取りを参照してください。 [例外](#reading-exceptions) は別々に処理されます。

参照 [認証 ](https://docs.realmjoin.com/ja/dev-reference/realmjoin-api/authentication)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 Status 200 (OK)

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

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

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

使用してください `/runbook/jobs/{jobID}/output/streams` を使用して、runbook の出力を包括的な JSON 形式で取得します。これにより `出力`, `Verbose` および `Error` stream [例外](#reading-exceptions) は別々に処理されます。

参照 [認証 ](https://docs.realmjoin.com/ja/dev-reference/realmjoin-api/authentication)Authorization ヘッダーの作成方法については、以下は単なる例です。

次の値が `jobID` であるとします `1234545e-7a24-436a-90c9-6056b512345`

**にアクセスできます。**

ヘッダー:

```http
Authorization: Basic dC0xMjM0MTIzNDpteVMzY3JldCE=
Content-Type: application/json
```

要求 / URI:

```html
リクエスト（すべてのストリーム）
```

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

**レスポンス**

Http Status 200 (OK)

GET <https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams>

```json
[
    {
        本文（JSON、メッセージの配列）
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "summary": "'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' のパスからモジュールを読み込んでいます。",
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "summary": "'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1' のパスからモジュールを読み込んでいます。",
        "summary": "RealmJoin.RunbookHelper: Azure Automation アカウントで実行中",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "time": "2021-12-20T08:37:47.1522235+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`を追加してリクエストにフィルターを追加できます。また、 `出力` および `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 Status 200 (OK)

GET <https://customer-api.realmjoin.com/runbook/jobs/1234545e-7a24-436a-90c9-6056b512345/output/streams>

```json
[
    {
        本文（JSON、メッセージの配列）
        "time": "2021-12-20T08:37:46.8572747+00:00",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "summary": "'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psd1' のパスからモジュールを読み込んでいます。",
        "time": "2021-12-20T08:37:46.9272241+00:00",
        "streamType": "Verbose",
        "streamText": null,
        "value": null
    },
    {
        "summary": "'C:\\Modules\\User\\RealmJoin.RunbookHelper\\RealmJoin.RunbookHelper.psm1' のパスからモジュールを読み込んでいます。",
        "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 の例外メッセージをシンプルなプレーンテキストで取得します（存在する場合）。これには `出力`, `Verbose` および `Error` stream [は含まれません。その他のストリームを読み取るには](#reading-specific-streams) ストリームの読み取りを参照してください。

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

この例では、中断を伴うエラーは `throw "Exception"`.

参照 [認証 ](https://docs.realmjoin.com/ja/dev-reference/realmjoin-api/authentication)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 Status 200 (OK)

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

```
Exception (Exception)
```