予約 API

リリースバージョン: Yokohama

更新日 2025年01月30日

所要時間：54分

Appointment API は、予約アプリケーションとやり取りするためのエンドポイントを提供します。この API を使用して、予約と再スケジュール、利用可能な予約スロットの確認、予約構成の詳細のフェッチを行います。

この API を使用する前に、予約設定とサービス設定を設定する必要があります。また、予約中のタスクが既に存在している必要があります。詳細については、「Configuring Appointment Booking」を参照してください。

Appointment API には Appointment Booking プラグイン (com.snc.appointment_booking) が必要であり、sn_apptmnt_booking 名前空間内で提供されます。この API にアクセスするには、snc_internal ロールが必要です。

予約:GET /sn_apptmnt_booking/appointment/calendar

予約できる時間範囲を返します。返品結果には、予約サービス構成で設定されたリードタイムと将来の最大予約可能日が遵守されます。

リードタイムと将来の最大予約可能日の構成の詳細については、 Create or modify an application configuration for Appointment Booking を参照してください。

このエンドポイントにアクセスするには、snc_internal ロールまたは snc_external ロールのいずれかが必要です。

URL 形式

バージョニングされた URL: /api/sn_apptmnt_booking/{api_version}/appointment/calendar

デフォルト URL: /api/sn_apptmnt_booking/appointment/calendar

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 1. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 2. クエリパラメーター
名前	説明
catalog_id	必須。予約サービス構成で構成されたレコードプロデューサーのSys_id。テーブル:レコードプロデューサー [sc_cat_item_producer] データタイプ：文字列
場所	必須。予約の場所のSys_id。テーブル:場所 [cmn_location] データタイプ：文字列
opened_for	必須。予約対象のユーザーのSys_id。テーブル:ユーザー [sys_user] データタイプ：文字列

表 : 3. 要求本文パラメーター
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 4. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 5. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 6. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
結果	エンドポイント要求の結果に関する情報。データタイプ: オブジェクト `"result": { "range_end": "String", "range_start": "String" }`
result.range_end	予約できる範囲の終了。 `範囲終了 = 本日 + 今後の最大予約可能日数` データタイプ：文字列形式:内部日時形式の予約のタイムゾーン。
result.range_start	予約できる範囲の開始。 `範囲開始 = 本日 + リードタイム` データタイプ：文字列形式:内部日時形式の予約のタイムゾーン。

cURL 要求

次のコード例は、このエンドポイントを呼び出す方法を示しています。

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/calendar?catalog_id=e4c1116b3b810300ce8a4d72f3efc40f&location=32e8499cdb2d2200d75270f5bf9619d6&opened_for=6816f79cc0a8016401c5a33be04be441" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Result (結果)：

{
  "result": {
    "range_start": "2023-02-08 03:52:27",
    "range_end": "2023-02-21 23:52:27"
  }
}

予約:GET /sn_apptmnt_booking/予約/構成

指定された予約サービス構成で定義された構成を返します。

さらに、予約ウィジェットにスロットを表示するために必要な翻訳とユーザーの日時設定を返します。

このエンドポイントにアクセスするには、snc_internal ロールまたは snc_external ロールのいずれかが必要です。

URL 形式

バージョニングされた URL: /api/sn_apptmnt_booking/{api_version}/appointment/configuration

デフォルト URL: /api/sn_apptmnt_booking/appointment/configuration

注:

サポートされている要求パラメーター

表 : 7. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 8. クエリパラメーター
名前	説明
catalog_id	必須。予約サービス構成で構成されたレコードプロデューサーのSys_id。データタイプ：文字列テーブル:レコードプロデューサー [sc_cat_item_producer]

表 : 9. 要求本文パラメーター
名前	説明
なし

ヘッダー

表 : 10. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 11. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

表 : 12. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
結果	エンドポイント要求の結果。データタイプ: オブジェクト `"result": { "active": Boolean, "active_string": "String", "advanced_calendar_view_portal": Boolean, "auto_acceptance": Boolean, "locale_language": "String", "service_config": {Object}, "task_table": "String", "translations": {Object}, "userDateFormatOptions": {Object}, "useRR": Boolean, "userTimeFormat": {Object}, "userTimeFormatOptions": {Object}, "view_scale": "String" }`
result.active	関連するカタログ ID のサービス構成セットアップがアクティブかどうかを示すフラグ。可能な値： true:カタログ ID のサービス構成セットアップがアクティブです。 false:カタログ ID のサービス構成セットアップがアクティブではありません。データタイプ：ブーリアン
result.active_string	関連付けられたカタログ ID のサービス構成セットアップのステータスのテキスト表現。データタイプ：文字列
result.advanced_calendar_view_portal	詳細カレンダービューをポータルに表示するか、基本ビューを表示するかを示すフラグ。詳細カレンダービューの詳細については、「 Create or modify an application configuration for Appointment Booking」を参照してください。可能な値： true:詳細カレンダービューがポータルに表示されます。 false:ポータルに基本ビューが表示されます。データタイプ：ブーリアン
result.auto_acceptance	予約が受け入れ済みステータスに自動的に移行するかどうかを示すフラグ。可能な値： true:予約は自動的に [承認済み] ステータスに移行します。 false:エージェントは手動で予約を受け入れる必要があります。データタイプ：ブーリアン
result.locale_language	ユーザーの言語設定。データタイプ：文字列形式:ISO 639.1 言語コード
result.service_config	サービス構成に関する詳細。データタイプ: オブジェクト `"service_config": { "active": Boolean, "active_string": "String", "appointment_booking_config": "String", "appointment_duration": "String", "appointments_per_bookable_slot": "String", "bookable_days": "String", "cancel_by_time": "String", "default_timezone": "String", "enable_advanced_config": Boolean, "field_mapping": {Object}, "future_bookable_max_days": "String", "lead_time": "String", "mandatory": "String", "use_slot_end_time_as": "String", "work_duration": "String" }`
result.service_config.active	予約サービス設定のアクティブステータスを示すフラグ。可能な値： true:アクティブ false:非アクティブデータタイプ：ブーリアン
result.service_config.active_string	予約サービス設定のステータスをテキストで表現します。データタイプ：文字列
result.service_config。appointment_booking_config	関連するカタログ ID の予約サービス構成セットアップのSys_id。データタイプ：文字列テーブル:予約サービスの設定 [sn_apptmnt_booking_service_config]
result.service_config。appointment_duration	予約の長さ。データタイプ：文字列単位：分
result.service_config。appointments_per_bookable_slot	関連付けられたスロットで予約可能な予約の数。データタイプ：文字列
result.service_config。bookable_days	予約できる日数を表すカンマ区切りの値。日は整数で表されます (月曜日 = 1 および日曜日 = 7)。データタイプ：文字列
result.service_config.cancel_by_time	予約の開始前にユーザーが予約をキャンセルできる最小時間。たとえば、午後 1:00 に予約していて、2 時間のキャンセル期限がある場合は、午前 10 時 59 分までに予約をキャンセルする必要があります。形式:この値は、「1970-01-01 00:00:00」との日時の差です。したがって、戻り値が「1970-01-01 04:00:00」の場合、会議開始の 4 時間前にルームをキャンセルする必要があることを意味します。データタイプ：文字列
result.service_config.default_timezone	予約するタイムゾーン設定。可能な値：場所:予約の場所のタイムゾーンを使用します。ユーザー:予約対象のユーザーのタイムゾーンを使用します。データタイプ：文字列
result.service_config。enable_advanced_config	予約時に予約構成と予約ルールを考慮するかどうかを示すフラグ。詳細については、「Create appointment booking advanced configuration」を参照してください。可能な値： true:予約時に、予約設定と予約ルールが考慮されます。 false:予約の設定と予約ルールは、予約時に考慮されません。データタイプ：ブーリアン
result.service_config.field_mapping	予約に使用される場所と連絡先の値にマッピングされたカタログ変数に関する詳細。データタイプ: オブジェクト `"field_mapping": { "contact": "String", "contactRPVariable": {Object}, "location": "String", "locationRPVariable": {Object} }`
result.service_config。field_mapping.contact	連絡先値を含むカタログ変数の名前。データタイプ：文字列
result.service_config.field_mapping。contactRPVariable	場所カタログ変数データの詳細。データタイプ: オブジェクト `"contactRPVariable": { "displayName": "String", "label": "String", "name": "String" }`
result.service_config.field_mapping。contactRPVariable.displayName	連絡先カタログ変数の表示名。データタイプ：文字列
result.service_config.field_mapping。contactRPVariable.label	連絡先カタログ変数のラベル。データタイプ：文字列
result.service_config.field_mapping。contactRPVariable.name	連絡先カタログ変数の名前。データタイプ：文字列
result.service_config。field_mapping.location	場所の値を含むカタログ変数の名前。データタイプ：文字列
result.service_config.field_mapping。locationRPVariable	場所カタログ変数データの詳細。データタイプ: オブジェクト `"locationRPVariable": { "displayName": "String", "label": "String", "name": "String" }`
result.service_config.field_mapping。locationRPVariable.displayName	場所カタログ変数の表示名。データタイプ：文字列
result.service_config.field_mapping。locationRPVariable.label	場所カタログ変数のラベル。データタイプ：文字列
result.service_config.field_mapping。locationRPVariable.name	場所カタログ変数の名前。データタイプ：文字列
result.service_config。future_bookable_max_days	予約できる将来の最大日数。データタイプ：文字列
result.service_config.lead_time	予約開始前のユーザーが予約できる最小時間。たとえば、午後 1:00 に予約する場合、リードタイムが 2 時間の場合、午前 10 時 59 分までに予約する必要があります。形式:この値は、「1970-01-01 00:00:00」との日時の差です。したがって、戻り値が「1970-01-01 04:00:00」の場合、会議開始の 4 時間前にルームを予約する必要があることを意味します。データタイプ：文字列
result.service_config.mandatory	予約が必須かどうかを示すインジケーター。可能な値： 0:予約は必須ではありません。 1:予約は必須です。データタイプ：文字列
result.service_config。use_slot_end_time_as	エージェントが到着する時間、または関連する予約にスケジュールされている作業を完了する時間に関するインジケーター。可能な値： arrive_by:エージェントは、指定されたタイムスロット内に予約の場所に到着します。 complete_by:エージェントは、指定されたタイムスロット内で予約の作業を完了します。 empty:completed_by と同じです。データタイプ：文字列
result.service_config.work_duration	予約の作業に要する時間。作業期間は、予約サービスの構成で構成されます。詳細については、「Create or modify service configuration for Appointment Booking」を参照してください。データタイプ：文字列単位：分
result.task_table	予約できるテーブルの名前。予約サービスの構成で構成されます。データタイプ：文字列
result.translations	予約ウィジェットで使用されるテキスト翻訳の名前と値のペア。アクション、メッセージ、日、および月の変換された値が含まれます。データタイプ: オブジェクト
result.userDateFormatOptions	JS 日付オブジェクトを表示するために必要な日付形式オプションについて説明します。これらの値は、変更できない予約定数で設定されます。データタイプ: オブジェクト `"userDateFormatOptions": { "day": "String", "month": "String", "week": "String", "weekday": "String" }`
result.userDateFormatOptions.day	日の日付形式。データタイプ：文字列形式:数値 (値または 1 〜 31)
result.userDateFormatOptions.month	月の日付形式。データタイプ：文字列形式:Short (Jan、Feb、Mar などの値)
result.userDateFormatOptions.week	週の日付形式。データタイプ：文字列形式:数値 (1 〜 5 の値)
result.userDateFormatOptions.weekday	平日の日付形式。データタイプ：文字列形式:Short (月、火、水などの値)
result.useRR	sn_apptmnt_booking.use_read_replica_from_ui プロパティの値。この値は、UI からクエリが実行されるときに、読み込みレプリカデータベースを使用して予約スロットをフェッチするかどうかを定義します。可能な値： true:読み込みレプリカデータベースを使用してスロットをフェッチします。 false:スロットのフェッチに読み込みレプリカデータベースを使用しません。データタイプ：ブーリアン
result.userTimeFormat	ユーザーの時間形式を記述します。ユーザーはエンドポイント要求を行うユーザーです。プラットフォームを介して作成された場合は、エージェントです。ポータルを介して作成された場合は、顧客です。データタイプ: オブジェクト `"userTimeFormat": { "type": "String", "value": "String" }`
result.userTimeFormat.type	時間形式のタイプ。可能な値： 12hr 24hr データタイプ：文字列
result.userTimeFormat.value	「HH:mm:ss」などの優先時間形式。データタイプ：文字列
result.userTimeFormatOptions	JS 時間オブジェクトをレンダリングするために必要な時間形式オプションについて説明します。これらの値は、変更できない予約定数で設定されます。データタイプ: オブジェクト `"userTimeFormatOptions": { "hour": "String", "hourCycle": "String", "minute": "String" }`
result.userTimeFormatOptions.hour	時間単位のフォーマット。形式:数値 (値 1 〜 12)
result.userTimeFormatOptions.hourCycle	時間単位の形式。可能な値は `h23` のみです。
result.userTimeFormatOptions.minute	分単位の形式。形式:数値 (1 〜 60 の値)
result.view_scale	サービス構成で構成されたビュー。可能な値：日週データタイプ：文字列

cURL 要求

次のコード例は、このエンドポイントを呼び出す方法を示しています。

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/configuration?catalog_id=e4c1116b3b810300ce8a4d72f3efc40f" \
--request GET \
--header "Accept:application/json" \
--user ‘username':'password'

応答：

{
  "result": {
    "active": true,
    "activeString": "true"
    "view_scale": "day",
    "auto_acceptance": true,
    "task_table": "wm_order",
    "advanced_calendar_view_portal": false,
    "service_config": {
      "appointment_booking_config": "deb1d2fd3b033200ce8a4d72f3efc4c2",
      "future_bookable_max_days": "14",
      "appointments_per_bookable_slot": "20",
      "bookable_days": "1,2,3,4,5",
      "active": true,
      "activeString": "true",
      "mandatory": "1",
      "lead_time": "1970-01-01 04:00:00",
      "cancel_by_time": "1970-01-01 04:00:00",
      "appointment_duration": "120",
      "default_timezone": "location",
      "work_duration": "60",
      "enable_advanced_config": true,
      "field_mapping": {
        "location": "location"
        "opened_for": "contact",
        "locationRPVariable": {
          "name": "location",
          "label": "Location",
          "displayName": "location"
        },
        "contactRPVariable": {
          "name": "contact",
          "label": "Contact",
          "displayName": "contact"
        }
      },
      "use_slot_end_time_as": ""
    },
    "translations": {
      "submit_btn_text": "Select",
      "cancel_btn_text": "Cancel",
      "calendar_prev_text": "Previous",
      "select_appointment_calendar_text": "Select Appointment Calendar",
      "calendar_next_text": "Next",
      "previous_btn_text": "Previous day",
      "next_btn_text": "Next day",
      "date_input_placeholder_text": "Pick a date",
      "show_calendar_btn_text": "Show Calendar",
      "app_window_btn_text_start_time": "Start time",
      "app_window_btn_text_end_time": "End time",
      "appointment_window_aria_label_start_text": "Available appointment window ",
      "no_appointment": "No appointments",
      "time_zone": "Time zone",
      "selected_window": "The window which has been selected is ",
      "day_names": {
        "1": "Monday",
        "2": "Tuesday",
        "3": "Wednesday",
        "4": "Thursday",
        "5": "Friday",
        "6": "Saturday",
        "7": "Sunday"
      },
      "days": [
        "Sunday",
        "Monday",
        "Tuesday",
        "Wednesday",
        "Thursday",
        "Friday",
        "Saturday"
      ],
      "daysShort": [
        "Sun",
        "Mon",
        "Tue",
        "Wed",
        "Thu",
        "Fri",
        "Sat"
      ],
      "daysMin": [
        "Su",
        "Mo",
        "Tu",
        "We",
        "Th",
        "Fr",
        "Sa"
      ],
      "months": [
        "January",
        "February",
        "March",
        "April",
        "May",
        "June",
        "July",
        "August",
        "September",
        "October",
        "November",
        "December"
      ],
      "monthsShort": [
        "Jan",
        "Feb",
        "Mar",
        "Apr",
        "May",
        "Jun",
        "Jul",
        "Aug",
        "Sep",
        "Oct",
        "Nov",
        "Dec"
      ],
      "today": "Today",
      "clear": "Clear",
      "language": "en",
      "arrive_by_msg": "The agent will arrive within the selected slot."
    },
    "useRR": true,
    "locale_language": "en",
    "userTimeFormat": {
      "value": "HH:mm:ss",
      "type": "24hr"
    },
    "userDateFormatOptions": {
      "weekday": "short",
      "year": "numeric",
      "month": "short",
      "day": "numeric"
    },
    "userTimeFormatOptions": {
      "hour": "numeric",
      "minute": "numeric",
      "hourCycle": "h23"
    }
  }
}

予約:GET /sn_apptmnt_booking/予約/execute_rule_conditions

指定されたタスクsys_idまたは指定されたカタログアイテムデータのセットに一致する予約サービス設定ルールのsys_idを返します。

渡されたタスク ID またはカタログアイテムデータは、サービス構成に定義されたルールに照らして評価されます。これらの条件が最初に一致するルールのsys_idが返されます。その後、このルールsys_id後続の可用性要求に渡して、ルールで定義されている正しいスロットをフェッチする必要があります。

このエンドポイントにアクセスするには、snc_internal ロールまたは snc_external ロールのいずれかが必要です。

URL 形式

バージョニングされた URL: /api/sn_apptmnt_booking/{api_version}/appointment/execute_rule_conditions

デフォルト URL: /api/sn_apptmnt_booking/appointment/execute_rule_conditions

注:

サポートされている要求パラメーター

表 : 13. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 14. クエリパラメーター
名前	説明
なし

表 : 15. 要求本文パラメーター
名前	説明
catalogId	必須。予約サービス構成で構成されたレコードプロデューサーのSys_id。データタイプ：文字列テーブル:レコードプロデューサー [sc_cat_item_producer]
otherInputs	taskIdパラメーターが指定されていない場合は必須です。サービス構成に定義されたルールと比較するカタログアイテム変数の名前と値のペア。例： `"otherInputs": { "u_sn_point_of_sale_variable_set": "true", "short_description": "Point-of-Sale Installation", "contact": "6816f79cc0a8016401c5a33be04be441", "description": "Install new point-of-sale system with cash tray", "location": "32e8499cdb2d2200d75270f5bf9619d6" }` データタイプ: オブジェクト
taskId	otherInputsパラメーターが指定されていない場合は必須です。予約しているタスクレコードのSys_id。予約が行われているタスクテーブルにあります。catalogIdは特定の予約設定に対応しており、すべての設定には予約を行うタスクテーブルがあります。データタイプ：文字列

ヘッダー

表 : 16. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 17. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

表 : 18. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
結果	エンドポイントによって返される情報の説明。データタイプ: オブジェクト `“result": { "dedicatedCapacity": Boolean, "futureMaxBookableDays": "String", "ruleId": "String", "ruleName": "String" }`
result.dedicatedCapacity	関連付けられたルールに専用のキャパシティがあるかどうかを示すフラグ。専用容量の詳細については、「 Create service configuration rules for a service configuration」を参照してください。可能な値： true:ルールには専用のキャパシティがあります。 false:キャパシティは関連付けられたルールと基本構成の間で共有されます。また、専用のキャパシティを持たない他のルールとも共有されます。データタイプ：ブーリアン
result.futureMaxBookableDays	一致ルールを使用して予約できる将来の最大日数。データタイプ：文字列
result.ruleId	要求で渡された taskId パラメーターまたは otherInputs パラメーターに一致する予約サービス設定ルールのSys_id。データタイプ：文字列テーブル:サービス構成ルール [sn_apptmnt_booking_config_rule]
result.ruleName	渡されたパラメーターに一致したルールの名前。データタイプ：文字列

cURL 要求

次のコード例は、 taskId パラメーターを使用してルール比較要求を行う方法を示しています。

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/execute_rule_conditions" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"taskId\": \"ce1f397c43b861105e0dbcba6ab8f298\"}" \
--user 'username':'password'

応答：

{
  "result": {
    "ruleId": "f7d5d98f437c21105e0dbcba6ab8f2fc",
    "ruleName": "Priority 1 rule",
    "dedicatedCapacity": true,
    "futureMaxBookableDays": "14"
  }
}

cURL 要求

次のコード例は、 otherInputs パラメーターを使用してルール比較要求を行う方法を示しています。

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/execute_rule_conditions" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"otherInputs\": {
    \"u_sn_point_of_sale_variable_set\": \"true\",
    \"short_description\": \"Point-of-Sale Installation\",
    \"contact\": \"6816f79cc0a8016401c5a33be04be441\",
    \"description\": \"Install new point-of-sale system with cash tray\",
    \"location\": \"32e8499cdb2d2200d75270f5bf9619d6\"
  }
}" \
--user 'username':'password'

応答：

{
  "result": {
    "ruleId": " 1d1bb72b4334a1105e0dbcba6ab8f275",
    "ruleName": "Lake View SC rule",
    "dedicatedCapacity": false,
    "futureMaxBookableDays": "21"
  }
}

予約 - POST /sn_apptmnt_booking/appointment/appointment

フィールドサービス管理 (FSM)タスクの予約と再スケジュールを行うことができます。

注:

このエンドポイントでは、関連する予約サービス構成で開始時刻と終了時刻が定義され、利用可能なスロットがある予定のみを予約およびスケジュールできます。

フィールドサービス管理 (FSM)タスクの詳細については、「Configuring Appointment Booking」を参照してください。

URL 形式

バージョニングされた URL: /api/sn_apptmnt_booking/{api_version}/appointment/appointment

デフォルト URL: /api/sn_apptmnt_booking/appointment/appointment

注:

サポートされている要求パラメーター

表 : 19. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 20. クエリパラメーター
名前	説明
なし

表 : 21. 要求本文パラメーター
名前	説明
actualEndDate	必須。予約のタイムゾーンでの予約スロットの終了日時。日付タイプ：文字列形式:YYYY-MM-dd HH:mm:ss
実際の開始日	必須。予約のタイムゾーンでの予約スロットの開始日時。日付タイプ：文字列形式:YYYY-MM-dd HH:mm:ss
catalogId	予約サービス構成用に構成されたレコードプロデューサーのSys_id。このパラメーターを渡さない場合、エンドポイントは taskId パラメーターと taskTable パラメーターからこの情報を識別しようとします。できない場合、エンドポイントは失敗し、エラーが返されます。日付タイプ：文字列テーブル:予約サービス構成 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
終了日 UTC	必須。UTC タイムゾーンの予約スロットの終了日時。日付タイプ：文字列形式:YYYY-MM-dd HH:mm:ss
場所	必須。予約に関連する場所レコードのSys_id。日付タイプ：文字列テーブル:場所 [cmn_location]
オープン対象	必須。予約対象のユーザーのSys_id。日付タイプ：文字列テーブル:ユーザー [sys_user]
reschedule	必須。予約が再スケジュールされているかどうかを示すフラグ。有効な値： true:予約は現在存在し、再スケジュールされています。 false:新規予約。データタイプ：ブーリアン
service_cofig_rule	予約がルールに基づいて予約されている場合は、サービス構成ルールのsys_id。日付タイプ：文字列テーブル:サービス構成ルール [sn_apptmnt_booking_config_rule]
開始日 UTC	必須。UTC タイムゾーンの予約スロットの開始日時。日付タイプ：文字列形式:YYYY-MM-dd HH:mm:ss
taskId	必須。予約しているタスクレコードのSys_id。日付タイプ：文字列テーブル: taskTable パラメーターで定義されます。
taskTable	必須。予約が行われているタスクレコードを含むテーブルの名前。日付タイプ：文字列
タイムゾーン	必須。指定された予約スロットを予約または更新するときに使用するタイムゾーン。形式:国/都市または地域の形式 (米国/東部など) 日付タイプ：文字列
validate_request	予約要求を検証するかどうかを示すフラグ。いずれかの検証が失敗すると、エンドポイントは失敗し、問題を説明するエラーメッセージが返されます。次の検証が実行されます。カタログ ID の検証:渡された catalogId パラメーターが有効なsys_idであることを確認します。タイムゾーンの検証:渡された timezone パラメーターが有効なタイムゾーンであることを確認します。タスク ID 検証:渡された taskId パラメーターが有効なsys_idであり、タスクがディスパッチ待ちステータスであることを確認します。重複するスロットの検証:再スケジュールの場合、元の予約と同じスロットを渡した場合、そのスロットは技術的に既に予約されているため、スロットは無効です。スロット検証:渡されたスロット情報が設定内容と一致し、スロットの期間が同じであることを確認します。たとえば、設定で 2 時間のスロットが設定されていても、3 時間のスロットを渡した場合、そのスロットは無効です。同様に、午前 9:00 から午前 11:00 のスロットが使用可能であるが、合格したスロットが午前 9 時 30 分から午前 11 時 30 分の場合、合格したスロットは無効です。有効な値： true:予約情報を検証します。 false:予約情報を検証しません。データタイプ：ブーリアンデフォルト値：false

ヘッダー

表 : 22. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 23. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

表 : 24. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
結果	エンドポイント要求の結果に関する情報。データタイプ: オブジェクト `"result": { "data": "String", "message": "String", "reason": "String", "success": Boolean }`
result.data	作成または再スケジュールされた予約レコードのSys_id。データタイプ：文字列
result.message	予約要求がスケジュール設定されたか失敗したかを説明するメッセージ。たとえば、エラー応答には次のものが含まれます。予約をスケジュールできません。予約を再スケジュールすることはできません。操作が成功すると、「予約が正常にスケジュールされました」のようなメッセージが返されます。データタイプ：文字列
result.reason	予約要求の結果に関する追加情報。データタイプ：文字列
result.success	要求が成功したかどうかを示すフラグ。可能な値： true:要求が成功しました false:要求は失敗しましたデータタイプ：ブーリアン

cURL 要求

次の例は、作業指示 [wm_order] テーブルのタスクの新しい予約を作成する方法を示しています。

curl "https://instance.servicenow.com/api/sn_apptmnt_booking/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"startDateUTC\": \"2023-02-01 20:00:00\",
\"endDateUTC\": \"2023-02-01 22:00:00\",
\"actualStartDate\": \"2023-02-01 15:00:00\",
\"actualEndDate\": \"2023-02-01 17:00:00\",
\"taskTable\": \"wm_order\",
\"location\": \"32e8499cdb2d2200d75270f5bf9619d6\",
\"catalogId\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
\"openedFor\": \"ddce70866f9331003b3c498f5d3ee417\"
\"taskId\": \"ce1f397c43b861105e0dbcba6ab8f298\",
\"reschedule\": false,
\"service_configuration_rule\": \"\",
\"timezone\": \"US/Eastern\"
}" \

--user 'username':'password'

応答：

{
"result": {
  "success": true,
  "message": "Your appointment has been scheduled successfully.",
  "reason": "Appointment created!",
  "data": "7a5f393c43b861105e0dbcba6ab8f29f"
  }
}

予約 - POST /sn_apptmnt_booking/予約/可用性

予約サービス設定で設定されているスロットを、その空き状況とともに返します。

サービス構成で詳細構成が有効になっている場合、エンドポイントはこれらの構成を優先し、ルールと詳細構成に従ってデータを返します。このエンドポイントを使用して、要求本文の get_next_available_slot パラメーターまたは get_next_available_day_data パラメーターを true として渡すことで、最初に利用可能なスロットを見つけることもできます。

このエンドポイントにアクセスするには、snc_internal ロールまたは snc_external ロールのいずれかが必要です。

URL 形式

バージョニングされた URL: /api/sn_apptmnt_booking/{api_version}/appointment/availability

デフォルト URL: /api/sn_apptmnt_booking/appointment/availability

注:

サポートされている要求パラメーター

表 : 25. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 26. クエリパラメーター
名前	説明
なし

表 : 27. 要求本文パラメーター
名前	説明
catalog_id	予約サービス構成用に構成されたレコードプロデューサーのSys_id。このパラメーターを渡さない場合、エンドポイントは taskId パラメーターと task_table パラメーターからこの情報を識別しようとします。できない場合、エンドポイントは失敗し、エラーが返されます。データタイプ：文字列テーブル:予約サービスの構成 [sn_apptmnt_booking_service_config] テーブルの関連レコードの [カタログアイテム] フィールド。
end_date	必須。予約をフェッチする終了日時。データタイプ：文字列形式:UTC タイムゾーンおよび形式 YYYY-MM-dd HH:mm:ss
fetch_days_slot	要求された日付範囲で毎日最初に利用可能なスロットを返すかどうかを示すフラグ。有効な値： true:各日の最初の利用可能なスロットを返します。 false:毎日最初に利用可能なスロットを返しません。データタイプ：ブーリアンデフォルト値：false
full_day	必須。開始日と終了日の時間値に関係なく、渡された指定された日付範囲のすべての予約を返すかどうかを示すフラグ。有効な値： true:指定された時間に関係なく、すべての予約を返します。 false:指定された日時に対応する予約のみを返します。データタイプ：ブーリアン
get_next_available_slot	最初に利用可能な予約スロットが、渡された start_date および end_date パラメーターに含まれていない場合でも、応答とともに返すかどうかを示すフラグ。有効な値： true:最初に利用可能な予約スロットを返します。 false:最初に利用可能な予約スロットを返しません。データタイプ：ブーリアンデフォルト値：false
limit	返される予約の最大数。データタイプ：数値デフォルト:sn_apptmnt_booking .max_appointments_ で返されたプロパティで指定された値。プロパティが空の場合は 1,000。
場所	必須。予約に関連付けられた場所レコードのSys_id。データタイプ：文字列テーブル:場所 [cmn_location]
opened_for	必須。予約対象のユーザーのSys_id。データタイプ：文字列テーブル:ユーザー [sys_user]
otherInputs	スクリプト化された手法で可用性を計算するために必要なその他の値の名前と値のペア。通常、これらの値はカタログアイテム変数ですが、予約アプリケーションをカスタマイズすると、実装に必要な値を渡すことができます。例： `"otherInputs": { "u_sn_point_of_sale_variable_set": "true", "short_description": "Point-of-Sale Installation", "contact": "6816f79cc0a8016401c5a33be04be441", "description": "Install new point-of-sale system with cash tray", "location": "32e8499cdb2d2200d75270f5bf9619d6" }` データタイプ: オブジェクト
service_config_rule	予約スロットと可用性の計算に使用するサービス構成ルールのSys_id。データタイプ：文字列テーブル:サービス構成ルール [sn_apptmnt_booking_config_rule]
start_date	必須。予約をフェッチする開始日時。データタイプ：文字列形式:UTC タイムゾーンおよび形式 YYYY-MM-dd HH:mm:ss
taskId	予約しているタスクレコードのSys_id。日付タイプ：文字列テーブル: taskTable パラメーターで定義されます。
task_table	必須。予約が行われているタスクレコードを含むテーブルの名前。データタイプ：文字列
use_read_replica	予約スロットとその可用性をフェッチするときに、データベースの読み取りレプリカを使用するかどうかを示すフラグ。有効な値： true:データベースの読み込みレプリカを使用します。 false:データベースの読み取りレプリカを使用しません。デフォルト値：false
view	必須。要求の作成元ポイント。有効な値： (大文字と小文字を区別) プラットフォーム portal データタイプ：文字列

ヘッダー

表 : 28. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 29. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

表 : 30. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
結果	要求に一致する予約の詳細。データタイプ: オブジェクト `"result": { "availability": [Array], "has_more": Boolean, "next_available_slot": {Object}, "no_appt_available": Boolean, "success": Boolean, "time_zone": "String", "time_zone_display_value": "String" }`
result.availability	指定された要求を満たす予約スロットのリスト。データタイプ：オブジェクトのアレイ `"availability": [{ "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" }]`
result.availability.available	関連付けられたタイムスロットが利用可能かどうかを示すフラグ。可能な値： true:タイムスロットが利用可能です。 false:タイムスロットは利用できません。データタイプ：ブーリアン
result.availability.end_date	関連付けられた予約の終了日時。タイムゾーンは、 time_zone パラメーターの値に基づいています。データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.availability.end_date_display	関連する予約の終了日時を表示します。タイムゾーンは、 time_zone_display_value パラメーターの値に基づいています。データタイプ：文字列形式:要求ユーザーの日時形式。
result.availability.end_dateUTC	関連する予約の終了日時 (UTC 時間)。データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.availability.start_date	関連する予約の開始日時。タイムゾーンは、 time_zone パラメーターの値に基づいています。データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.availability.start_date_display	関連する予約の開始日時を表示します。タイムゾーンは、 time_zone_display_value パラメーターの値に基づいています。データタイプ：文字列形式:要求ユーザーの日時形式。
result.availability.start_dateUTC	関連付けられた予約の開始日時 (UTC 時間) データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.has_more	制限を返した後にフェッチする予約スロットがさらにあるかどうかを示すフラグ。可能な値： true:より多くの予約スロットが利用可能です。 false:利用可能なスロットがこれ以上ありません。データタイプ：ブーリアン
result.next_available_slot	get_next_available_slotパラメーターが true として渡された場合は、渡された開始日と終了日に関係なく、最初に利用可能なスロットの詳細。データタイプ: オブジェクト `"next_available_slot": { "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" }`
result.next_available_slot.available	関連付けられたタイムスロットが利用可能かどうかを示すフラグ。可能な値： true:タイムスロットが利用可能です。 false:タイムスロットは利用できません。データタイプ：ブーリアン
result.next_available_slot.end_date	関連付けられた予約の終了日時。タイムゾーンは、 time_zone パラメーターの値に基づいています。データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.next_available_slot.end_date_display	関連する予約の終了日時を表示します。タイムゾーンは、 time_zone_display_value パラメーターの値に基づいています。データタイプ：文字列
result.next_available_slot.end_dateUTC	関連する予約の終了日時 (UTC 時間)。データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.next_available_slot.start_date	関連する予約の開始日時。タイムゾーンは、 time_zone パラメーターの値に基づいています。データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.next_available_slot.start_date_display	関連する予約の開始日時を表示します。タイムゾーンは、 time_zone_display_value パラメーターの値に基づいています。データタイプ：文字列
result.next_available_slot.start_dateUTC	関連付けられた予約の開始日時 (UTC 時間) データタイプ：文字列形式：YYYY-MM-DD hh:mm:ss
result.no_appt_available	指定された日時に利用可能な予約スロットが他にもあるかどうかを示すフラグ。可能な値： true:より多くの予約時間枠が利用可能です。 false:予約のタイムスロットはこれ以上利用できません。データタイプ：ブーリアン
result.success	エンドポイント呼び出しが成功したかどうかを示すフラグ。可能な値： true：エンドポイントコールに成功しました。 false：エンドポイントコールに失敗しました。データタイプ：ブーリアン
result.time_zone	予約スロットがレンダリングされたタイムゾーン。予約サービス設定の値に基づいています。データタイプ：文字列
result.time_zone_display_value	予約スロットがレンダリングされたタイムゾーンを表示します。予約サービス設定の値に基づいています。データタイプ：文字列

cURL 要求

次のコード例は、このエンドポイントを呼び出す方法を示しています。

curl "http://instance.servicenow.com/api/sn_apptmnt_booking/v1/appointment/availability" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"start_date\": \"2023-02-05 05:00:00\",
  \"end_date\": \"2023-02-07 04:59:59\",
  \"location\": \"32e8499cdb2d2200d75270f5bf9619d6\",
  \"catalog_id\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"opened_for\": \"6816f79cc0a8016401c5a33be04be441\",
  \"full_day\": false,
  \"task_table\": \"wm_order\",
  \"view\": \"portal\",
  \"get_next_available_slot\": true,
  \"use_read_replica\": true,
  \"service_config_rule\": \"f7d5d98f437c21105e0dbcba6ab8f2fc\"
}" \
--user 'username':'password

応答：

{
"result": {
  "success": true,
  "availability": [
    {
      "start_date": "2023-02-06 09:00:00",
      "end_date": "2023-02-06 11:00:00",
      "start_date_display": "09:00",
      "end_date_display": "11:00",
      "start_dateUTC": "2023-02-06 14:00:00",
      "end_dateUTC": "2023-02-06 16:00:00",
      "available": false
    },
    {
      "start_date": "2023-02-06 13:00:00",
      "end_date": "2023-02-06 15:00:00",
      "start_date_display": "13:00",
      "end_date_display": "15:00",
      "start_dateUTC": "2023-02-06 18:00:00",
      "end_dateUTC": "2023-02-06 20:00:00",
      "available": false
    },
    {
      "start_date": "2023-02-06 15:00:00",
      "end_date": "2023-02-06 17:00:00",
      "start_date_display": "15:00",
      "end_date_display": "17:00",
      "start_dateUTC": "2023-02-06 20:00:00",
      "end_dateUTC": "2023-02-06 22:00:00",
      "available": false
    }
  ],
  "has_more": false,
  "no_appt_available": true,
  "time_zone": "US/Eastern",
  "time_zone_display_value": "US/Eastern",
  "next_available_slot": {
    "start_date": "2023-02-10 13:00:00",
    "end_date": "2023-02-10 15:00:00",
    "start_date_display": "13:00",
    "end_date_display": "15:00",
    "start_dateUTC": "2023-02-10 18:00:00",
    "end_dateUTC": "2023-02-10 20:00:00",
    "available": true
}