> 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/zi-dong-hua/runbooks/runbook-references/org/devices/notify-users-about-stale-devices_scheduled.md).

# 古いデバイスについてユーザーに通知（スケジュール済み）

プライマリ ユーザーに、その古いデバイスについてメールで通知します

{% hint style="info" %}
これはスケジュール実行の runbook です。単一のオブジェクトでトリガーされるのではなく、繰り返しスケジュールで実行されるように設計されています。詳細は [スケジューリング](/ja/zi-dong-hua/runbooks/scheduling.md) runbook のスケジュールの構成方法についてご覧ください。
{% endhint %}

### 説明

指定した日数、アクティブでなかったデバイスを特定し、それらのデバイスのプライマリ ユーザーにパーソナライズされたメール通知を送信します。メールにはデバイス情報とユーザー向けの対応手順が含まれます。必要に応じて、特定のグループを含める／除外することでユーザーをフィルターできます。利用可能なルーティング先は3つあります。すべての通知を転送するグローバル オーバーライド受信者（テストおよびパイロット用）、UPN が名前パターンに一致するユーザー向けの専用受信者（例: Device Enrollment Manager アカウント）、およびプライマリ ユーザーのいない非アクティブなデバイスについて1通にまとめたメールを受け取る専用受信者です。

### メール送信に関するセットアップ

メール レポートの送信は任意であり、受信者（`EmailTo`) が指定された場合にのみ行われます。送信者アドレスは `RJReport.EmailSender` テナント設定から取得されます。

この runbook は Microsoft Graph API を使用してメールを送信します。Graph API 経由でメールを送信するには、runbook のカスタマイズで既存のメールアドレスを構成する必要があります。

以下を参照してください [RealmJoin レポート設定ドキュメント](https://docs.realmjoin.com/automation/runbooks/runbook-report-settings) 利用可能なすべての設定の詳細について。

#### メールのブランド設定

レポートメールは、任意の `RJReport.Branding.*` テナント設定に従います:

* **ヘッダーおよびフッター画像** – 公開 HTTPS URL、PNG/JPEG/GIF、各最大 200 KB
* **フッターリンク** – フッター画像のリンク先
* **アクセント色とテキスト色** – 6 桁の 16 進数値、例: `#0052cc`

これらの設定が構成されていない場合、既定の RealmJoin のグラフィックと色が使用されます。ダウンロードまたは検証できない画像や無効な色の値が、レポートメールを妨げることはありません。代わりに対応する既定値が使用されます。

セットアップ手順と画像要件: [メールのブランド設定](https://docs.realmjoin.com/automation/runbooks/runbook-report-settings#email-branding-optional).

### メール テンプレート言語の選択

このランブックは 3 種類のメール テンプレート オプションをサポートしています:

1. **EN（英語 - 既定）**：組み込みの英語テンプレートを使用します
2. **DE（ドイツ語）**：組み込みのドイツ語テンプレートを使用します
3. **カスタム**：Runbook Customizations のカスタム テンプレートを使用します

#### カスタム メール テンプレートの使用

カスタム メール テンプレート（たとえばオランダ語、スペイン語、またはその他の言語）を使用するには、Runbook Customizations でテンプレート テキストを構成する必要があります。カスタム テンプレート パラメーターが 1 つでも不足している場合、ランブックは自動的に英語テンプレートにフォールバックします。

**例: カスタム テンプレート**

```json
{
    "Runbooks": {
        "rjgit-org_devices_notify-users-about-stale-devices_scheduled": {
            "Parameters": {
                "CustomMailTemplateSubject": {
                    "Default": "カスタム件名 - 要対応: 非アクティブなデバイス"
                },
                "CustomMailTemplateBeforeDeviceDetails": {
                    "Default": "**これはデバイス詳細の上に表示されます。** \n\n親愛なるユーザーの皆さま ..."
                },
                "CustomMailTemplateAfterDeviceDetails": {
                    "Default": "**これはデバイス詳細の下に表示されます。** \n\n## 実施すべきこと..."
                }
            }
        }
    }
}
```

**重要な注意事項:**

* 使用してください `\n` JSON 構成で改行するために
* テンプレート テキストでは Markdown 書式（##、###、\*\*、-）を使用できます
* 3 つのカスタム テンプレート パラメーター（Subject、BeforeDeviceDetails、AfterDeviceDetails）はすべて構成する必要があります
* いずれかのパラメーターが欠けている場合、ランブックは自動的に英語（EN）テンプレートにフォールバックします
* カスタム テンプレートを使用する場合は、Mail Template ドロップダウンで「Custom - Use Template from Runbook Customizations」を選択してください

### メール ルーティング

ランブックは3つの独立したルーティング先を認識しており、次の優先順位で確認します:

1. **グローバル オーバーライド（テスト）:** 設定された `OverrideEmailRecipient` は **ALL** メール（ユーザー通知、パターンに基づく通知、およびプライマリ ユーザーのいないデバイス向けのまとめたメール）をそのアドレスに送信します。エンドユーザーにはメールは届きません。テスト、パイロット、またはすべてを共有メールボックスやチケットシステムにルーティングする場合に使用します。オーバーライドが有効な間は、実行ごとに警告がログに記録されます。
2. **パターンに一致したユーザー:** 〜の場合 `OverrideUserNamePattern` が設定されている場合、UPN がパターンに一致するユーザーの通知は `UserNamePatternEmailRecipient` に送信され、ユーザー本人には送られません。その他のユーザーの通知は直接本人に送信されます。典型的な用途: Device Enrollment Manager またはキオスク アカウント（`DEM-*`, `KIOSK-*`）など、誰もメールボックスを読まないアカウントです。
3. **プライマリ ユーザーのいないデバイス:** 〜の場合 `SendNoPrimaryUserDevicesToOverride` が有効な場合、プライマリ ユーザーのいない非アクティブなデバイスは **1通の** まとめたメールとして `NoPrimaryUserEmailRecipient`に集約されます。そうでない場合、これらのデバイスはスキップされます。この設定は、ユーザー通知のルーティング方法を変更しません。

不完全な設定がある場合、ランブックはエンドユーザーに気づかれないようにメールを送るのではなく、エラーで停止します:

* `SendNoPrimaryUserDevicesToOverride` が有効なのに `NoPrimaryUserEmailRecipient` がなく、（グローバル オーバーライドもない）- エラー。
* `OverrideUserNamePattern` が設定されているのに `UserNamePatternEmailRecipient` がなく、（グローバル オーバーライドもない）- エラー。
* 機能がないまま設定された受信者（`NoPrimaryUserEmailRecipient` トグルがないまま、 `UserNamePatternEmailRecipient` パターンがないまま）- 警告。受信者は無視されます。

グローバル オーバーライドが有効な間は、専用の受信者を設定する必要はありません。いずれにせよ、すべてがオーバーライド先の受信者に送られます。

#### ユーザー名パターン

`OverrideUserNamePattern` は、プライマリ ユーザーの UPN と照合される1つ以上のワイルドカード パターン（カンマ区切り）を受け付けます。例: `DEM-*` Device Enrollment Manager アカウントの場合、または `DEM-*,KIOSK-*` のように複数パターンを指定できます。照合は大文字小文字を区別せず、PowerShell のワイルドカード構文（`*`, `?`）を使用します。パターン ルーティングが有効な場合、ランブックはどのパターンがどの受信者に転送されるかを示す警告をログに記録します。

**重要な注意事項:**

* すべての受信者パラメーターは、カンマ区切りの複数アドレスを受け付けます
* プライマリ ユーザーのいないデバイスは、ユーザー スコープ フィルタリングをバイパスします（グループと照合するユーザーがいないため）
* パターンに一致したユーザーは、まずユーザー スコープ フィルタリングの対象になります。スコープから除外されたユーザーには通知は一切送られません
* プライマリ ユーザーのいないデバイス向けのまとめたメールは、カスタム テンプレートとは独立した管理向けの文面（エンドユーザー向けの対応手順なし）を使用します
* リダイレクトされた通知では、メールの件名と本文に対象ユーザーが明記されます

### 場所

組織 → デバイス → 期限切れのデバイスについてユーザーに通知する（スケジュール済み）

**完全な runbook 名**

rjgit-org\_devices\_notify-users-about-stale-devices\_scheduled

### 詳細

| プロパティ    | 値                                                                                       |
| -------- | --------------------------------------------------------------------------------------- |
| バージョン    | 1.7.0                                                                                   |
| 必要なモジュール | <p>RealmJoin.RunbookHelper (>= 0.8.9)<br>Microsoft.Graph.Authentication (>= 2.39.0)</p> |
| スケジュール可能 | はい                                                                                      |

### 注記

このランブックは、指定した日数同期されていないデバイスを持つユーザーに、パーソナライズされたメール通知を自動送信します。メールはプライマリ ユーザーのメール アドレスに直接送信され、各非アクティブなデバイスの詳細情報が含まれます。

前提条件:

* EmailFrom パラメーターは、Runbook Customizations で設定する必要があります（RJReport.EmailSender 設定）
* 任意: Service Desk の連絡先情報を構成できます（ServiceDesk\_DisplayName、ServiceDesk\_EMail、ServiceDesk\_Phone、ServiceDesk\_PortalUrl）

一般的な使用例:

* 定期的なデバイス確認を促すため、非アクティブなデバイスについてユーザーに自動リマインダーを送る
* デバイスが廃止される前にユーザーへ通知することで、プロアクティブなデバイス ライフサイクル管理を実現
* 登録済みのすべてのデバイスをユーザーに把握してもらうことで、セキュリティとコンプライアンスを確保
* MaxDays パラメーターを使用した段階的な通知（例: 30日後に最初のリマインダー、60日後に最終通知）
* 特定の部署を対象にする、またはサービス アカウントを除外するためのユーザー スコープ フィルタリング
* 専用の受信者を使って、プライマリ ユーザーのいないデバイスや Device Enrollment Manager（例: DEM-\*）アカウントが所有するデバイスを一元的に処理する

パイロットおよびテストのオプション:

* OverrideEmailRecipient パラメーターを使用して、すべての通知をエンドユーザーではなくテスト用メールボックスに送信する
* 本番展開前にメール内容を検証し、フィルターをテストするのに最適
* 通知をチケットシステムや共有メールボックスに送信して、一元管理する

### アクセス許可

#### アプリケーションのアクセス許可

* **種類**: Microsoft Graph
  * DeviceManagementManagedDevices.Read.All
    * *lastSyncDateTime でフィルターされた Intune 管理デバイスを読み取り、非アクティブなデバイスとそのプライマリ ユーザーを見つけます*
  * Directory.Read.All
    * *メールフッター用にテナント名を読み取り、グループ スコープ フィルタリング用にユーザー ID を解決します*
  * Group.Read.All
    * *どのプライマリ ユーザーに通知するかを絞り込むために、含める／除外するグループのメンバーを一覧表示します*
  * Mail.Send
    * *非アクティブなデバイス通知メールを、各プライマリ ユーザーまたはオーバーライド先受信者に送信します*

### パラメーター

#### 日数

非アクティブと見なすまでの、活動がない日数。最小しきい値。

| プロパティ   | 値              |
| ------- | -------------- |
| 必須      | いいえ            |
| 既定値     | 30             |
| 種類      | Int32          |
| ポータル表示名 | 非アクティブと見なす最小日数 |

#### MaxDays

非アクティブ日数の最大値（省略可）。設定すると、Days と MaxDays の間で非アクティブなデバイスのみが含まれます。

| プロパティ   | 値                  |
| ------- | ------------------ |
| 必須      | いいえ                |
| 既定値     |                    |
| 種類      | Int32              |
| ポータル表示名 | (省略可) 非アクティブ日数の最大値 |

#### Windows

結果に Windows デバイスを含めます。

| プロパティ   | 値                |
| ------- | ---------------- |
| 必須      | いいえ              |
| 既定値     | True             |
| 種類      | ブール値             |
| ポータル表示名 | Windows デバイスを含める |

#### macOS

結果に macOS デバイスを含めます。

| プロパティ   | 値              |
| ------- | -------------- |
| 必須      | いいえ            |
| 既定値     | True           |
| 種類      | ブール値           |
| ポータル表示名 | macOS デバイスを含める |

#### iOS

結果に iOS デバイスを含めます。

| プロパティ   | 値            |
| ------- | ------------ |
| 必須      | いいえ          |
| 既定値     | True         |
| 種類      | ブール値         |
| ポータル表示名 | iOS デバイスを含める |

#### Android

結果に Android デバイスを含めます。

| プロパティ   | 値                |
| ------- | ---------------- |
| 必須      | いいえ              |
| 既定値     | True             |
| 種類      | ブール値             |
| ポータル表示名 | Android デバイスを含める |

#### EmailFrom

送信者のメール アドレスです。runbook のカスタマイズで構成する必要があります。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### BrandingHeaderImageUrl

レポートメール用のカスタムヘッダー画像（PNG/JPEG/GIF、最大 200 KB）の任意の公開 HTTPS URL。RJReport.Branding.HeaderImageUrl テナント設定から取得されます。空の場合は既定の RealmJoin ヘッダー画像が使用されます。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### BrandingFooterImageUrl

レポートメール用のカスタムフッター画像（PNG/JPEG/GIF、最大 200 KB）の任意の公開 HTTPS URL。RJReport.Branding.FooterImageUrl テナント設定から取得されます。空の場合は既定の RealmJoin フッター画像が使用されます。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### BrandingFooterLink

フッター画像がリンクする任意の URL。RJReport.Branding.FooterLink テナント設定から取得されます。空の場合は既定のリンク（<https://www.realmjoin.com）が使用されます。>

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### BrandingAccentColor

レポートメール テンプレート用の任意のアクセント色の上書き（6 桁の 16 進数、例: '#0052cc'）。RJReport.Branding.AccentColor テナント設定から取得されます。空または無効な場合は、既定の RealmJoin アクセント色が使用されます。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### BrandingTextColor

レポートメール テンプレート用の任意のテキスト色の上書き（6 桁の 16 進数）。RJReport.Branding.TextColor テナント設定から取得されます。空または無効な場合は、既定の RealmJoin テキスト色が使用されます。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### ServiceDeskDisplayName

ユーザー連絡先情報用の Service Desk 表示名（任意）。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### ServiceDeskEmail

ユーザー連絡先情報用の Service Desk メール アドレス（任意）。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### ServiceDeskPhone

ユーザー連絡先情報用の Service Desk 電話番号（任意）。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### ServiceDeskPortalUrl

クリック可能なリンクとして表示される、ユーザー連絡先情報用の Service Desk ポータル URL（任意）。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### ServiceDeskTicketUrl

クリック可能なリンクとして表示される Service Desk チケットへの直接リンク（任意）。既定では空であり、チケット リンクは追加されません。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### UseUserScope

グループ メンバーシップに基づいてユーザーを含めたり除外したりするために、ユーザー スコープ フィルタリングを有効にします。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       | False                    |
| 種類        | ブール値                     |
| ポータル表示名   | ユーザー スコープ フィルタリングを使用     |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### IncludeUserGroup

このグループのメンバーであるユーザーにのみメールを送信します。UseUserScope を有効にする必要があります。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータル表示名   | 含めるユーザー (グループ)           |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### ExcludeUserGroup

このグループのメンバーであるユーザーにはメールを送信しません。UseUserScope を有効にする必要があります。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータル表示名   | 除外するユーザー (グループ)          |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### OverrideEmailRecipient

任意: グローバル オーバーライド - 設定すると、すべての通知（ユーザー通知、パターンに基づく通知、およびプライマリ ユーザーのいないデバイス向けのまとめたメール）は、通常の受信者の代わりにこのアドレスに送信されます。複数の受信者をカンマ区切りで指定できます。テスト、パイロット、またはすべてをチケットシステムにルーティングする場合に最適です。空欄のままにすると通常のルーティングが適用されます。

| プロパティ   | 値                        |
| ------- | ------------------------ |
| 必須      | いいえ                      |
| 既定値     |                          |
| 種類      | 文字列                      |
| ポータル表示名 | \* ALL \* のメールを上書き受信者に転送 |

#### OverrideUserNamePattern

プライマリ ユーザーの UPN に一致する任意のワイルドカード パターン（カンマ区切り、例: 'DEM-*,KIOSK-*'、大文字小文字を区別しません）。一致したユーザーの通知は UserNamePatternEmailRecipient にリダイレクトされ、その他のユーザーには直接メールが送信されます。グローバル オーバーライド（OverrideEmailRecipient）が有効な間は、すべての通知がリダイレクトされるため、個別には評価されません。

| プロパティ   | 値                                                  |
| ------- | -------------------------------------------------- |
| 必須      | いいえ                                                |
| 既定値     |                                                    |
| 種類      | 文字列                                                |
| ポータル表示名 | （任意）プライマリ ユーザー名パターン - 一致したユーザーをリダイレクト（例: 'DEM-\*'） |

#### UserNamePatternEmailRecipient

OverrideUserNamePattern に一致するユーザーの通知を受け取るメール アドレス。カンマ区切りで指定できます。OverrideUserNamePattern が設定されている場合、OverrideEmailRecipient が設定されていない限り必須です。

| プロパティ   | 値                 |
| ------- | ----------------- |
| 必須      | いいえ               |
| 既定値     |                   |
| 種類      | 文字列               |
| ポータル表示名 | パターンに一致したユーザーの受信者 |

#### SendNoPrimaryUserDevicesToOverride

有効にすると、プライマリ ユーザーのいない非アクティブなデバイスは1通のまとめたメールとして NoPrimaryUserEmailRecipient に集約されます（グローバル オーバーライド有効時は OverrideEmailRecipient へ送信）。ユーザー通知のルーティング方法は変更されません。プライマリ ユーザーのいないデバイスはユーザー スコープ フィルタリングをバイパスします。

| プロパティ     | 値                                 |
| --------- | --------------------------------- |
| 必須        | いいえ                               |
| 既定値       | False                             |
| 種類        | ブール値                              |
| ポータル表示名   | プライマリ ユーザーのいないデバイスをまとめたメールとして送信する |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定）          |

#### NoPrimaryUserEmailRecipient

プライマリ ユーザーのいない非アクティブなデバイス向けのまとめたメールを受け取るメール アドレス。カンマ区切りで指定できます。SendNoPrimaryUserDevicesToOverride が有効な場合、OverrideEmailRecipient が設定されていない限り必須です。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータル表示名   | プライマリ ユーザーのいないデバイスの受信者   |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### MailTemplateLanguage

使用するメール テンプレートを選択します: EN（英語、既定）、DE（ドイツ語）、または Custom（Runbook Customizations から）。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       | EN                       |
| 種類        | 文字列                      |
| ポータル表示名   | メール テンプレート               |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### CustomMailTemplateSubject

カスタムのメール件名（MailTemplateLanguage が 'Custom' に設定されている場合にのみ使用されます）。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータル表示名   | カスタム: メール件名              |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### CustomMailTemplateBeforeDeviceDetails

デバイス一覧の前に表示するカスタム テキスト（MailTemplateLanguage が 'Custom' に設定されている場合にのみ使用されます）。Markdown 書式をサポートします。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータル表示名   | カスタム: デバイス一覧の前のテキスト      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

#### CustomMailTemplateAfterDeviceDetails

デバイス一覧の後に表示するカスタム テキスト（MailTemplateLanguage が 'Custom' に設定されている場合のみ使用されます）。Markdown 書式をサポートします。

| プロパティ     | 値                        |
| --------- | ------------------------ |
| 必須        | いいえ                      |
| 既定値       |                          |
| 種類        | 文字列                      |
| ポータル表示名   | カスタム: デバイス一覧の後のテキスト      |
| ポータルでは非表示 | はい（runbook のカスタマイズで事前設定） |

[Runbook Reference の概要に戻る](/ja/zi-dong-hua/runbooks/runbook-references.md)


---

# 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/zi-dong-hua/runbooks/runbook-references/org/devices/notify-users-about-stale-devices_scheduled.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.