予約 API

リリースバージョン: Xanadu

更新日 2024年08月01日

所要時間：52分

予約 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 appointment booking application configuration を参照してください。

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

URL 形式

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

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

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

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

表 : 2. クエリパラメーター
名前	説明
catalog_id	必須。予約サービス設定で構成されたレコードプロデューサーのSys_id。レコードプロデューサー [sc_cat_item_producer] テーブルにあります。データタイプ：文字列
場所	必須。予約の場所 (cmn_location) の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": {
    "range_start": "2023-02-08 03:52:27",
    "range_end": "2023-02-21 23:52:27"
  }
}

予約:GET /sn_apptmnt_booking/appointment/configuration

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

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

このエンドポイントにアクセスするには、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 appointment booking application configuration」を参照してください。可能な値： 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 時に予約していて、時間までに 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.連絡先	連絡先の値を含むカタログ変数の名前。データタイプ：文字列
result.service_config.field_mapping。接触式RPVariable	場所カタログ変数データの詳細。データタイプ: オブジェクト `"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.場所	場所の値を含むカタログ変数の名前。データタイプ：文字列
result.service_config.field_mapping。ロケーションRPVariable	場所カタログ変数データの詳細。データタイプ: オブジェクト `"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.必須	予約が必須かどうかを示すインジケーター。可能な値： 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 an appointment booking service configuration」を参照してください。データタイプ：文字列単位：分
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	月の日付形式。データタイプ：文字列形式:短い (1 月、2 月、3 月などの値)
result.userDateFormatOptions.week	週の日付形式。データタイプ：文字列形式: 数値 (1 から 5 の値)
result.userDateFormatOptions.weekday	平日の日付形式。データタイプ：文字列形式:短い (月、火、水などの値)
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	サービス構成で構成されたビュー。可能な値：日 week データタイプ：文字列

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/appointment/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] テーブルにあります。データタイプ：文字列
その他の入力	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 appointment booking service configuration rules」を参照してください。可能な値： 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. 要求本文パラメーター
名前	説明
実績終了日	必須。予約のタイムゾーンでの予約スロットの終了日時。日付タイプ：文字列形式:YYYY-MM-dd HH:mm:ss
実績開始日	必須。予約のタイムゾーンでの予約スロットの開始日時。日付タイプ：文字列形式:YYYY-MM-dd HH:mm:ss
catalogId	必須。予約サービス設定用に設定されたレコードプロデューサーのSys_id。レコードプロデューサーは、関連する予約サービス設定レコード - 予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [ カタログアイテム ] フィールドで定義されます。日付タイプ：文字列
終了日 UTC	必須。予約スロットの終了日時 (UTC タイムゾーン)。日付タイプ：文字列形式:YYYY-MM-dd HH:mm:ss
場所	必須。予約に関連する場所レコードのSys_id。場所 [cmn_location] テーブルにあります。日付タイプ：文字列
openedFor	必須。予約しているユーザーのSys_id。ユーザー [sys_user] テーブルにあります。日付タイプ：文字列
reschedule	必須。予約が再スケジュールされているかどうかを示すフラグ。有効な値： true:予約が現在存在し、スケジュールを変更しています。 false:新規予約。データタイプ：ブーリアン
service_cofig_rule	予約がルールに基づいて予約されている場合は、サービス構成ルールのsys_id。サービス構成ルール [sn_apptmnt_booking_config_rule] テーブルにあります。日付タイプ：文字列
startDateUTC	必須。予約スロットの開始日時 (UTC タイムゾーン)。日付タイプ：文字列形式:UTC タイムゾーンの YYYY-MM-dd HH:mm:ss
taskId	必須。予約されているタスクレコードのSys_id。このsys_idを含むテーブルは、 taskTable パラメーターで定義されます。日付タイプ：文字列
タスクテーブル	必須。予約されているタスクレコードを含むテーブルの名前。日付タイプ：文字列
タイムゾーン	必須。指定された予約スロットを予約または更新するときに使用するタイムゾーン。形式:国/都市またはエリア形式 (米国/東部など) 日付タイプ：文字列

ヘッダー

表 : 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	予約要求がスケジュールされたか失敗したかを説明するメッセージ。たとえば、エラー応答には次のようなものがあります。予約をスケジュールできません。予約を再スケジュールすることはできません。操作が正常に完了すると、次のようなメッセージが返されます。Your appointment has been scheduled successfully. データタイプ：文字列
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/appointment/availability

予約サービス構成で構成されているスロットを、その可用性とともに返します。

サービス構成に対して詳細構成が有効になっている場合、エンドポイントはこれらの構成を受け入れ、ルールと詳細構成に従ってデータを返します。このエンドポイントを使用して、要求本文の 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。レコードプロデューサーは、関連する予約サービス設定レコード - 予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [ カタログアイテム ] フィールドで定義されます。データタイプ：文字列
end_date	必須。予約をフェッチする終了日時。データタイプ：文字列形式:UTC タイムゾーンおよび内部日付と時刻の形式 YYYY-MM-DD HH:MM:SS
full_day	必須。開始日と終了日の時間値に関係なく、渡された指定された日付範囲のすべての予約を返すかどうかを示すフラグ。可能な値： true:指定した時間に関係なく、すべての予定を返します。 false:指定された日時に対応する予約のみを返します。データタイプ：ブーリアン
get_next_available_slot	最初に利用可能な予約スロットが、渡された start_date および end_date パラメーターに含まれていない場合でも、応答とともに返すかどうかを示すフラグ。可能な値： true:最初に利用可能な予約スロットを返します。 false:最初に利用可能な予約スロットを返さない。データタイプ：ブーリアンデフォルト値：false
limit	返される予約の最大数。データタイプ：数値デフォルト:sn_apptmnt_booking .max_appointments_ returned プロパティで指定された値。プロパティが空の場合は 1000。
場所	必須。予約に関連付けられた場所レコードのSys_id。場所 [cmn_location] テーブルにあります。データタイプ：文字列
opened_for	必須。予約しているユーザーのSys_id。ユーザー [sys_user] テーブルにあります。データタイプ：文字列
その他の入力	スクリプト化されたメソッドで可用性を計算するために必要なその他の値の名前と値のペア。通常、これらの値はカタログアイテム変数ですが、予約アプリケーションをカスタマイズする場合は、実装に必要な値を渡すことができます。例： `"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
task_table	必須。予約されているタスクレコードを含むテーブルの名前。データタイプ：文字列
use_read_replica	予約スロットとその可用性をフェッチするときに、データベースの読み込みレプリカを使用するかどうかを示すフラグ。有効な値： true:データベースの読み込みレプリカを使用します。 false:データベースの読み込みレプリカを使用しません。デフォルト値：false
表示	必須。要求の発信元ポイント。有効な値： (大文字と小文字を区別) プラットフォーム 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.利用可能	関連付けられたタイムスロットが利用可能かどうかを示すフラグ。可能な値： 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 パラメーターの値に基づいています。データタイプ：文字列 Format (形式)：
result.next_available_slot.終了日UTC	関連する予定の終了日時 (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 パラメーターの値に基づいています。データタイプ：文字列 Format (形式)：
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
}