予約オープン API

Appointment Open API は、予約アプリケーションを操作できるようにする電気通信 API です。この API を使用して、予約を行い、利用可能な時間帯を検索します。

Appointment Open API は、Open API TMForum TMF646 Appointment REST API 仕様のServiceNow®実装であり、TM Forum の適合認定を受けています。この実装は、 TMF646 Appointment API REST Specification R16.0.1 に基づいています。

この API には、 ServiceNow Store で利用可能な次のプラグインが必要です。

• 予約 (com.snc.appointment_booking)
• Field Service Management (フィールドサービス管理 (FSM)) (com.snc.work_management)
• 電気通信のフィールドサービス管理 (com.sn_fsmt)
• 電気通信オープン API (com.sn_tmf_api)

この API を使用する前に、予約設定とサービス設定を設定する必要があります。さらに、予約が取り込まれているタスクが存在する必要があります。

この API は sn_tmf_api 名前空間内で提供されます。呼び出し元ユーザーには、sn_tmf_api.appointment_integrator ロールが必要です。

オープン予約:GET /api/sn_tmf_api/appointment/searchTimeSlot

予約サービス構成で設定されたタイムスロットとその可用性を返します。

URL 形式

/api/sn_tmf_api/appointment/searchTimeSlot

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

表 : 1. パスパラメーター

名前	説明
なし

表 : 2. クエリパラメータ

名前	説明
catalog_id	必須。予約サービス構成で構成されたレコードプロデューサーのSys_id。 データタイプ：文字列 テーブル:レコードプロデューサー [sc_cat_item_producer]
end_date	必須。予約を検索する期間の終了日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例: 2025-01-31 12:00:00。
場所	予約の場所のSys_id。 テーブル:場所 [cmn_location] データタイプ：文字列 デフォルト:指定されていない場合は、すべての場所を返します。
opened_for	必須。予約対象のユーザーのSys_id。 テーブル:連絡先 [customer_contact] データタイプ：文字列
start_date	必須。予約を検索する期間の開始日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例: 2025-01-31 09:00:00。

表 : 3. 要求本文パラメーター

名前	説明
なし

ヘッダー

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

表 : 4. 要求ヘッダー

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

表 : 5. 応答ヘッダー

ヘッダー	説明
なし

ステータスコード

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

表 : 6. ステータスコード

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

応答本文のパラメーター

名前	説明
availableTimeSlot	要求された指定された時間ブロック内の予約スロットのリスト。 データタイプ：オブジェクトのアレイ 'availableTimeSlot': [ { "available": Boolean, "end_date": "String", "end_date_display": "String", "end_dateUTC": "String", "start_date": "String", "start_date_display": "String", "start_dateUTC": "String" } ]
availableTimeSlot.available	関連付けられたタイムスロットが利用可能かどうかを示すフラグ。 可能な値： true:タイムスロットが利用可能です。 false:タイムスロットは利用できません。 データタイプ：ブーリアン
availableTimeSlot.end_date	関連付けられた予約の終了日時。タイムゾーンは、 timeZone パラメーターの値に基づいています。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
availableTimeSlot.end_date_display	関連する予約の終了日時を表示します。タイムゾーンは、 timeZone パラメーターの値に基づいています。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
availableTimeSlot.end_dateUTC	関連付けられた予約の終了日時。 データタイプ：文字列 形式：UTC
availableTimeSlot.start_date	関連する予約の開始日時。timeZoneパラメーターの値を反映します。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
availableTimeSlot.start_date_display	関連する予約の開始日時を表示します。timeZoneパラメーターの値を反映します。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
availableTimeSlot.start_dateUTC	関連する予約の開始日時。 データタイプ：文字列 形式：UTC
hasMore	制限を返した後にフェッチする予約スロットがさらにあるかどうかを示すフラグ。この制限は、予約プロパティ sn_apptmnt_booking.max_appointments_returned (デフォルト:100) で指定されます。このプロパティの詳細については、 Appointment booking components を参照してください。 可能な値： true:より多くの予約スロットをフェッチできます。 false:利用可能な予約スロットがありません。 データタイプ：ブーリアン
noApptAvailable	指定された日時に利用可能な予約スロットが他にもあるかどうかを示すフラグ。 有効な値： true:指定された日時に、より多くの予約スロットが利用可能です。 false:指定された日時に利用できる予約スロットがなくなります。 データタイプ：ブーリアン
検索結果	指定された検索タイムスロット内での予約の空き状況の結果。 可能な値： 正常終了 失敗 データタイプ：文字列
ステータス	利用可能なタイムスロット検索の完了ステータス。たとえば、done です。 データタイプ：文字列
タイムゾーン	指定された予約スロットを予約または更新するときに使用されるタイムゾーン。 日付タイプ：文字列 形式:米国/東部などの国/都市または地域の形式

cURL 要求

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

curl --location --request GET 'https://instance.service-now.com/api/sn_tmf_api/appointment/searchTimeSlot?
start_date=2024-07-10 09:00:00&end_date=2024-07-20 23:00:00&catalog_id=ada50a93f0220210f8776517d8c8e776&
opened_for=51670151c35420105252716b7d40ddfe&location=f48b21850a0a0ba7004182b18099696d ' \
--user 'username':'password'

結果：

{
  "searchResult": "success",
  "status": "done",
  "availableTimeSlot": [
    {
      "start_date": "2024-07-10 09:00:00",
      "end_date": "2024-07-10 12:00:00",
      "start_date_display": "09:00",
      "end_date_display": "12:00",
      "start_dateUTC": "2024-07-10 16:00:00",
      "end_dateUTC": "2024-07-10 19:00:00",
      "available": false
    },
    {
      "start_date": "2024-07-11 13:00:00",
      "end_date": "2024-07-11 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-11 20:00:00",
      "end_dateUTC": "2024-07-11 23:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-12 09:00:00",
      "end_date": "2024-07-12 12:00:00",
      "start_date_display": "09:00",
      "end_date_display": "12:00",
      "start_dateUTC": "2024-07-12 16:00:00",
      "end_dateUTC": "2024-07-12 19:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-12 13:00:00",
      "end_date": "2024-07-12 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-12 20:00:00",
      "end_dateUTC": "2024-07-12 23:00:00",
      "available": true
    },
    {
      "start_date": "2024-07-19 13:00:00",
      "end_date": "2024-07-19 16:00:00",
      "start_date_display": "13:00",
      "end_date_display": "16:00",
      "start_dateUTC": "2024-07-19 20:00:00",
      "end_dateUTC": "2024-07-19 23:00:00",
      "available": true
    }
  ],
  "hasMore": false,
  "noApptAvailable": false,
  "timeZone": "US/Arizona"
}

予約オープン:POST /api/sn_tmf_api/appointment/appointment

作業指示書の予約を行うことができます。

URL 形式

/api/sn_tmf_api/appointment/appointment

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

表 : 7. パスパラメーター

名前	説明
なし

表 : 8. クエリパラメータ

名前	説明
なし

表 : 9. 要求本文パラメーター

名前	説明
カテゴリ	必須。予約サービス構成用に構成されたレコードプロデューサーのSys_id。 データタイプ：文字列 テーブル:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
relatedEntity	必須。予約に関連付ける、影響を受ける作業指示のリスト。 データタイプ：オブジェクトのアレイ "relatedEntity": [ { "@referredType": "String" "id": "String", } ]
relatedEntity.@referredType	必須。アイテムまたはサービスのタイプ。 有効な値:WorkOrder データタイプ：文字列 テーブル:作業指示 [wm_order]
relatedEntity.id	必須。関連エンティティのSys_id。 データタイプ：文字列 テーブル:workOrder [wm_order] デフォルト:sys_idが指定されていない場合は、すべてを返します。
relatedEntity.role	必須。関連エンティティのロールの説明。 有効な値:作業指示 データタイプ：文字列 テーブル:作業指示 [wm_order]
relatedParty	必須。予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。要求には、顧客アカウント情報を含むアイテムが少なくとも 1 つリストされている必要があります。 データタイプ：オブジェクトのアレイ "relatedParty": [ { "@referredType": "String", "id": "String", "name": "String", "role": "String" } ]
relatedParty.@referredType	顧客のタイプ。 有効な値:個々 データタイプ：文字列
relatedParty.id	必須。作業指示書に関連付けられている連絡先のSys_idまたはexternal_id。 データタイプ：文字列 テーブル:連絡先 [customer_contact]
relatedParty.name	連絡先の名前。 データタイプ：文字列 テーブル:連絡先 [customer_contact]
relatedParty.role	必須。連絡先のロール。 可能な値： 顧客:連絡先には顧客ロールがあります。 技術者:連絡先には技術者ロールがあります。 データタイプ：文字列 テーブル:連絡先 [customer_contact]
関連する場所	必須。予約に関連する場所のリスト。 データタイプ：オブジェクトのアレイ "relatedPlace": [ { "@referredType": "String", "id": "String", "name": "String", "role": "String" } ]
relatedPlace.@referredType	必須。場所のタイプ。例:市区町村。 データタイプ：文字列 テーブル:場所 [cmn_location]
relatedPlace.id	必須。関連する場所のSys_id。 データタイプ：文字列 テーブル:場所 [cmn_location]
relatedPlace.name	連絡先に関連する場所の名前。例:251 Reddy St, Darwin, CA 93522。 データタイプ：文字列 テーブル:場所 [cmn_location]
relatedPlace.role	必須。場所ロールの説明。たとえば、作業指示書などです。 データタイプ：文字列
タイムゾーン	必須。指定された予約スロットを予約するときに使用するタイムゾーン。 日付タイプ：文字列 形式:米国/東部などの国/都市または地域の形式
validFor	必須。予約が有効な日付範囲。 データタイプ: オブジェクト "validFor": { "endDateTime": "String", "startDateTime": "String" }
validFor.endDateTime	必須。タイムスロットの終了日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
validFor.startDateTime	必須。タイムスロットの開始日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

ヘッダー

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

表 : 10. 要求ヘッダー

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

表 : 11. 応答ヘッダー

ヘッダー	説明
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

ステータスコード

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

表 : 12. ステータスコード

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

応答本文のパラメーター

名前	説明
カテゴリ	予約サービス構成用に構成されたレコードプロデューサーのSys_id。 データタイプ：文字列 保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
creationDate	予約が作成された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
href	予約レコードへのハイパーリンク。別の予約オープン API 要求でこのリンクを使用して、予約を再スケジュールまたは削除します。 データタイプ：文字列
ID	予約のSys_id。 データタイプ：文字列 保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブル
lastUpdate	予約が最後に更新された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
relatedEntity	予約の関連エンティティに関する詳細。 データタイプ：オブジェクトのアレイ "relatedEntity": [ { "@referredType": "String", "id": "String", "role": "String" } ]
relatedEntity.@referredType	アイテムまたはサービスのタイプ。 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedEntity.id	関連エンティティのSys_id。 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedEntity.role	関連エンティティのロールの説明。 可能な値:作業指示 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedParty	予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。 データタイプ：オブジェクトのアレイ "relatedParty": [ { "@referredType": "String", "id": "String", "name": " String", "role": "String" } ]
relatedParty.@referredType	顧客のタイプ。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.id	作業指示書に関連付けられている顧客連絡先のSys_id。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.name	顧客の連絡先の名前。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.role	顧客連絡先のロール。 可能な値： 顧客:連絡先には顧客ロールがあります。 技術者:連絡先には技術者ロールがあります。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
関連する場所	関連する予約の場所の詳細。 データタイプ: オブジェクト "relatedPlace": { "@referredType": "String", "id": "String", "name": "String", "role": "String" }
relatedPlace.@referredType	予約の地理的な住所。 可能な値:GeographicLocation。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.id	場所のSys_id。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.name	連絡先に関連する場所の名前。例:100 South Charles Street, Baltimore, MD。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.role	介入住所としての予約場所のロール。 可能な値:InterventionAddress データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
正常終了	要求が成功したかどうかを示すフラグ。 可能な値： true:要求が成功しました。 false:要求は失敗しました。 データタイプ：ブーリアン
タイムゾーン	指定された予約スロットを予約または更新するときに使用されるタイムゾーン。 日付タイプ：文字列 形式:米国/東部などの国/都市または地域の形式
validFor	予約が有効な日付範囲。 データタイプ: オブジェクト "validFor": { "endDateTime": "String" "startDateTime": "String" }
validFor.endDateTime	予約の終了日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
validFor.startDateTime	予約の開始日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

cURL 要求

次の例は、新しい予約を作成する方法を示しています。

curl "https://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"validFor\": {
    \"startDateTime\": \"2024-08-19 09:00:00\",
    \"endDateTime\": \"2024-08-19 11:00:00\"
  },
  \"category\": \"e4c1116b3b810300ce8a4d72f3efc40f\",
  \"relatedParty\": [
    {
      \"id\": \"eaf68911c35420105252716b7d40ddde\",
      \"name\": \"Sally Thomas\",
      \"role\": \"customer\",
      \"@referredType\": \"Individual\"
    }
  ],
  \"relatedPlace\": {
    \"id\": \"25ab9c4d0a0a0bb300f7dabdc0ca7c1c\",
    \"name\": \"100 South Charles Street, Baltimore,MD\",
    \"role\": \"interventionAddress\",
    \"@referredType\": \"GeographicAddress\"
  },
  \"relatedEntity\": [
    {
      \"id\": \"48dbfbf9201f0250f877303e8a020dcd\",
      \"role\": \"work order\",
      \"@referredType\": \"WorkOrder\"
    }
  ],
  \"timeZone\": \"US/Arizona\"
}" \
--user 'username':'password'

応答：

{
  "validFor": {
    "startDateTime": "2024-07-19 09:00:00",
    "endDateTime": "2024-07-19 11:00:00"
  },
  "category": "e4c1116b3b810300ce8a4d72f3efc40f",
  "relatedParty": [
    {
      "id": "eaf68911c35420105252716b7d40ddde",
      "name": "Sally Thomas",
      "role": "customer",
      "@referredType": "Individual"
    }
  ],
  "relatedPlace": {
    "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
    "name": "100 South Charles Street, Baltimore,MD",
    "role": "interventionAddress",
    "@referredType": "GeographicAddress"
  },
  "relatedEntity": [
    {
      "id": "48dbfbf9201f0250f877303e8a020dcd",
      "role": "work order",
      "@referredType": "WorkOrder"
    }
  ],
  "timeZone": "US/Arizona",
  "success": true,
  "id": "feacb7f9201f0250f877303e8a020d38",
  "href": "api/sn_tmf_api/appointment/appointment/feacb7f9201f0250f877303e8a020d38",
  "creationDate": "2024-07-10 22:45:01",
  "lastUpdate": "2024-07-10 22:45:01"
}

予約オープン - DELETE /api/sn_tmf_api/appointment/appointment/{id}

指定された ID の予約レコードを削除します。

URL 形式

デフォルト URL: /api/sn_tmf_api/appointment/appointment/{id}

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

表 : 13. パスパラメーター

名前	説明
ID	削除する予約レコードのSys_id。 データタイプ：文字列 テーブル:予約 [sn_apptmnt_booking_appointment_booking]

表 : 14. クエリパラメーター

名前	説明
なし

表 : 15. 要求本文パラメーター (XML または JSON)

名前	説明
なし

ヘッダー

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

表 : 16. 要求ヘッダー

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

表 : 17. 応答ヘッダー

ヘッダー	説明
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

ステータスコード

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

表 : 18. ステータスコード

ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
404	見つかりません。要求されたアイテムが見つかりませんでした。

応答本文のパラメーター (JSON)

名前	説明
メッセージ	削除が正常に完了したことを確認する応答メッセージ。 成功:「予約 (<id>) が正常にキャンセルされました。」 エラー： 「予約のキャンセルに失敗しました。(Appointment cancellation failed.)」:システムで ID が見つからないため、404 ステータスコードが返されます。 "予約のキャンセルに失敗しました。":予約は既にキャンセル済みまたは完了済みステータスであるか、削除できず、404 ステータスコードを返します。 「予約 (<id>) はキャンセル期限を超えているため、キャンセルできません。」:予約は、予約サービス設定で設定されている [キャンセル期限] を既に超えています。400 ステータスコードを返します。 データタイプ：文字列

cURL 要求

次の例では、特定の ID を持つ予約を削除します。

curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373" \ 
--request GET\ 
--user 'username':'password' 

応答本文：

"The appointment (68cc0a5a9314521060320dd548373cbd) is successfully cancelled."

予約オープン:GET /api/sn_tmf_api/appointment/appointment/{id}

指定された ID に関連付けられた予約レコードを取得します。

URL 形式

デフォルト URL: /api/sn_tmf_api/appointment/appointment/{id}

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

表 : 19. パスパラメーター

名前	説明
ID	取得する予約のSys_id。 データタイプ：文字列 テーブル:予約 [sn_apptmnt_booking_appointment_booking]

表 : 20. クエリパラメーター

名前	説明
カテゴリ	予約をカテゴリsys_idでフィルタリングします。 データタイプ：文字列 テーブル:場所 [cmn_location] デフォルト:カテゴリsys_idが指定されていない場合は、すべての予約を返します。
relatedEntity	作業指示に関連付けられた関連エンティティの詳細。 データタイプ: オブジェクト "relatedEntity": { "id": "String" }
relatedEntity.id	必須。関連エンティティのSys_id。 データタイプ：文字列 テーブル:workOrder [wm_order] デフォルト:sys_idが指定されていない場合は、すべてを返します。
relatedParty	予約に関連付けられた関係者のsys_idで予約をフィルタリングします。 データタイプ: オブジェクト "relatedParty": { "id": "String", "name": "String" } デフォルト: relatedParty が指定されていない場合は、すべての予約を返します。
relatedParty.id	関係者の sys_id。 データタイプ：文字列 テーブル： ユーザー [sys_user]
relatedParty.name	関係者の名前。 データタイプ：文字列
関連する場所	サービスまたは修理がスケジュールされている場所で予約をフィルタリングします。 データタイプ: オブジェクト "relatedPlace": { "id": "String" } デフォルト: relatedPlace が指定されていない場合は、すべての予約を返します。
relatedPlace.id	関連する場所のSys_id。 データタイプ：文字列 テーブル:場所 [cmn_location]
validFor	予約が有効な日付範囲で予約をフィルタリングします。 データタイプ: オブジェクト "validFor": { "endDateTime": "String", "startDateTime": "String" } デフォルト: validFor が指定されていない場合は、すべての予約を返します。
validFor.endDateTime	予約の終了日時。指定された終了日時の予約のみが応答で返されます。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。 テーブル:場所 [cmn_location]
validFor.startDateTime	予約の開始日時。指定された開始日時の予約のみが応答に返されます。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。 テーブル:場所 [cmn_location]

表 : 21. 要求本文パラメーター (XML または JSON)

名前	説明
なし

ヘッダー

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

表 : 22. 要求ヘッダー

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

表 : 23. 応答ヘッダー

ヘッダー	説明
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

ステータスコード

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

表 : 24. ステータスコード

ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
404	見つかりません。要求されたアイテムが見つかりませんでした。

応答本文のパラメーター

名前	説明
カテゴリ	予約サービス構成用に構成されたレコードプロデューサーのSys_id。 データタイプ：文字列 保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
creationDate	予約が作成された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
href	予約レコードへのハイパーリンク。別の予約オープン API 要求でこのリンクを使用して、予約を再スケジュールまたは削除します。 データタイプ：文字列
ID	予約のSys_id。 データタイプ：文字列 保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブル
lastUpdate	予約が最後に更新された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
relatedEntity	予約の関連エンティティに関する詳細。 データタイプ：オブジェクトのアレイ "relatedEntity": [ { "@referredType": "String", "id": "String", "role": "String" } ]
relatedEntity.@referredType	アイテムまたはサービスのタイプ。 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedEntity.id	関連エンティティのSys_id。 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedEntity.role	関連エンティティのロールの説明。 可能な値:作業指示 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedParty	予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。 データタイプ：オブジェクトのアレイ "relatedParty": [ { "@referredType": "String", "id": "String", "name": " String", "role": "String" } ]
relatedParty.@referredType	顧客のタイプ。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.id	作業指示書に関連付けられている顧客連絡先のSys_id。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.name	顧客の連絡先の名前。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.role	顧客連絡先のロール。 可能な値： 顧客:連絡先には顧客ロールがあります。 技術者:連絡先には技術者ロールがあります。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
関連する場所	関連する予約の場所の詳細。 データタイプ: オブジェクト "relatedPlace": { "@referredType": "String", "id": "String", "name": "String", "role": "String" }
relatedPlace.@referredType	予約の地理的な住所。 可能な値:GeographicLocation。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.id	場所のSys_id。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.name	連絡先に関連する場所の名前。例:100 South Charles Street, Baltimore, MD。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.role	介入住所としての予約場所のロール。 可能な値:InterventionAddress データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
validFor	予約が有効な日付範囲。 データタイプ: オブジェクト "validFor": { "endDateTime": "String" "startDateTime": "String" }
validFor.endDateTime	予約の終了日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
validFor.startDateTime	予約の開始日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

cURL 要求

次の例では、指定された予約レコード ID に従って予約の詳細を返します。

curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9" \ 
--request GET\ 
--user 'username':'password'

応答本文：

[
  {
    "id": "201071ad4f80d210f8992fec52ce0ba9",
    "href": "api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9",
    "validFor": {
      "startDateTime": "2024-08-16 17:00:00",
      "endDateTime": "2024-08-16 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
      "name": "100 South Charles Street, Baltimore,MD",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "b440a5694f40d210f8992fec52ce0ba3",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-16 00:39:22",
    "lastUpdate": "2024-08-16 00:39:22"
  }
]

予約オープン:GET /api/sn_tmf_api/appointment/appointment

予約レコードリストを取得します。

URL 形式

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

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

表 : 25. パスパラメーター

名前	説明
なし

表 : 26. クエリパラメーター

名前	説明
カテゴリ	予約をカテゴリsys_idでフィルタリングします。 データタイプ：文字列 テーブル:場所 [cmn_location] デフォルト:カテゴリsys_idが指定されていない場合は、すべての予約を返します。
relatedEntity	作業指示に関連付けられた関連エンティティの詳細。 データタイプ: オブジェクト "relatedEntity": { "id": "String" }
relatedEntity.id	必須。関連エンティティのSys_id。 データタイプ：文字列 テーブル:workOrder [wm_order] デフォルト:sys_idが指定されていない場合は、すべてを返します。
relatedParty	予約に関連付けられた関係者のsys_idで予約をフィルタリングします。 データタイプ: オブジェクト "relatedParty": { "id": "String", "name": "String" } デフォルト: relatedParty が指定されていない場合は、すべての予約を返します。
relatedParty.id	関係者の sys_id。 データタイプ：文字列 テーブル： ユーザー [sys_user]
relatedParty.name	関係者の名前。 データタイプ：文字列
関連する場所	サービスまたは修理がスケジュールされている場所で予約をフィルタリングします。 データタイプ: オブジェクト "relatedPlace": { "id": "String" } デフォルト: relatedPlace が指定されていない場合は、すべての予約を返します。
relatedPlace.id	関連する場所のSys_id。 データタイプ：文字列 テーブル:場所 [cmn_location]
validFor	予約が有効な日付範囲で予約をフィルタリングします。 データタイプ: オブジェクト "validFor": { "endDateTime": "String", "startDateTime": "String" } デフォルト: validFor が指定されていない場合は、すべての予約を返します。
validFor.endDateTime	予約の終了日時。指定された終了日時の予約のみが応答で返されます。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。 テーブル:場所 [cmn_location]
validFor.startDateTime	予約の開始日時。指定された開始日時の予約のみが応答に返されます。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。 テーブル:場所 [cmn_location]

表 : 27. 要求本文パラメーター (XML または JSON)

名前	説明
なし

ヘッダー

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

表 : 28. 要求ヘッダー

ヘッダー	説明
承認	応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。 デフォルト： application/json

表 : 29. 応答ヘッダー

ヘッダー	説明
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

ステータスコード

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

表 : 30. ステータスコード

ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
404	見つかりません。要求されたアイテムが見つかりませんでした。

応答本文のパラメーター (JSON または XML)

名前	説明
カテゴリ	予約サービス構成用に構成されたレコードプロデューサーのSys_id。 データタイプ：文字列 保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブルの [カタログアイテム] フィールド。
creationDate	予約が作成された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
href	予約レコードへのハイパーリンク。別の予約オープン API 要求でこのリンクを使用して、予約を再スケジュールまたは削除します。 データタイプ：文字列
ID	予約のSys_id。 データタイプ：文字列 保存場所:予約サービス設定 [sn_apptmnt_booking_service_config] テーブル
lastUpdate	予約が最後に更新された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
relatedEntity	予約の関連エンティティに関する詳細。 データタイプ：オブジェクトのアレイ "relatedEntity": [ { "@referredType": "String", "id": "String", "role": "String" } ]
relatedEntity.@referredType	アイテムまたはサービスのタイプ。 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedEntity.id	関連エンティティのSys_id。 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedEntity.role	関連エンティティのロールの説明。 可能な値:作業指示 データタイプ：文字列 保存場所:workOrder [wm_order] テーブル
relatedParty	予約の連絡先のリスト。各連絡先はアレイ内のオブジェクトです。 データタイプ：オブジェクトのアレイ "relatedParty": [ { "@referredType": "String", "id": "String", "name": " String", "role": "String" } ]
relatedParty.@referredType	顧客のタイプ。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.id	作業指示書に関連付けられている顧客連絡先のSys_id。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.name	顧客の連絡先の名前。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.role	顧客連絡先のロール。 可能な値： 顧客:連絡先には顧客ロールがあります。 技術者:連絡先には技術者ロールがあります。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
関連する場所	関連する予約の場所の詳細。 データタイプ: オブジェクト "relatedPlace": { "@referredType": "String", "id": "String", "name": "String", "role": "String" }
relatedPlace.@referredType	予約の地理的な住所。 可能な値:GeographicLocation。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.id	場所のSys_id。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.name	連絡先に関連する場所の名前。例:100 South Charles Street, Baltimore, MD。 データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
relatedPlace.role	介入住所としての予約場所のロール。 可能な値:InterventionAddress データタイプ：文字列 保存場所:場所 [cmn_location] テーブル
validFor	予約が有効な日付範囲。 データタイプ: オブジェクト "validFor": { "endDateTime": "String" "startDateTime": "String" }
validFor.endDateTime	予約の終了日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
validFor.startDateTime	予約の開始日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。

cURL 要求

次の例は、GET appointment メソッドを使用して予定のリストを返す方法を示しています。

curl "http://instance.servicenow.com/api/sn_tmf_api/appointment/appointment" \ 
--request GET\ 
--user 'username':'password' 

応答本文には、予約サービス設定で設定された 2 つの異なる予約の詳細が含まれています。

[
  {
    "id": "201071ad4f80d210f8992fec52ce0ba9",
    "href": "api/sn_tmf_api/appointment/appointment/201071ad4f80d210f8992fec52ce0ba9",
    "validFor": {
      "startDateTime": "2024-08-16 17:00:00",
      "endDateTime": "2024-08-16 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "25ab9c4d0a0a0bb300f7dabdc0ca7c1c",
      "name": "100 South Charles Street, Baltimore,MD",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "b440a5694f40d210f8992fec52ce0ba3",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-16 00:39:22",
    "lastUpdate": "2024-08-16 00:39:22"
  },
  {
    "id": "25c012c07f5c5610f8994fa63c866523",
    "href": "api/sn_tmf_api/appointment/appointment/25c012c07f5c5610f8994fa63c866523",
    "validFor": {
      "startDateTime": "2024-08-26 17:00:00",
      "endDateTime": "2024-08-26 19:00:00"
    },
    "category": "4a34a64d4f4c1210f8992fec52ce0b63",
    "relatedParty": [
      {
        "id": "eaf68911c35420105252716b7d40ddde",
        "name": " null",
        "role": "customer",
        "@referredType": "Individual"
      }
    ],
    "relatedPlace": {
      "id": "f48b21850a0a0ba7004182b18099696d",
      "name": "11251 Rancho Carmel Drive, San Diego,CA",
      "role": "interventionAddress",
      "@referredType": "Individual"
    },
    "relatedEntity": [
      {
        "id": "c0b09a047f109610f8994fa63c8665b4",
        "role": "work order",
        "@referredType": "WorkOrder"
      }
    ],
    "creationDate": "2024-08-23 22:18:43",
    "lastUpdate": "2024-08-23 22:18:43"
  }
]

予約オープン - PATCH /api/sn_tmf_api/appointment/appointment/{id}

作業指示書に対して指定された ID で予約を再スケジュールします。

URL 形式

デフォルト URL: PATCH /api/sn_tmf_api/appointment/appointment/{id}

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

表 : 31. パスパラメーター

名前	説明
ID	再スケジュールする予約のSys_id。 データタイプ：文字列 テーブル:予約 [sn_apptmnt_booking_appointment_booking]

表 : 32. クエリパラメーター

名前	説明
なし

表 : 33. 要求本文パラメーター (JSON)

名前	説明
注意	予約をキャンセルする場合は、ここで作業メモを追加できます。作業指示書の作業メモと予約のメッセージを更新します。 データタイプ：オブジェクトのアレイ "note": [ { "author": "String", "date": "String", "text": "String" } ] 保存場所:予約 [sn_apptmnt_booking_appointment_booking] テーブル
note.author	メモの書き込み者の名前。 データタイプ：文字列
note.date	メモが公開された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2018-02-04T11:00:18.071Z。
note.text	予約に添付されている作業指示書に関する説明テキスト。たとえば、作業指示書の進捗状況の更新などです。 データタイプ：文字列
ステータス	予約のステータス。 有効な値： キャンセル:予約の再スケジュールがキャンセルされます。 completed:再スケジュールされた予約が完了しました。 confirmed:予約の再スケジュールが承認され、予約されました。 新規:予約の再スケジュール要求が最近作成されました。 pending:予約の再スケジュールが保留中です。 準備完了:予約の再スケジュールが要求されました。 データタイプ：文字列
validFor	予約が有効な日付範囲で予約をフィルタリングします。 データタイプ: オブジェクト "validFor": { "endDateTime": "String", "startDateTime": "String" } デフォルト: validFor が指定されていない場合は、すべての予約を返します。
validFor.endDateTime	予約の終了日時。指定された終了日時の予約のみが応答で返されます。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。 テーブル:場所 [cmn_location]
validFor.startDateTime	予約の開始日時。指定された開始日時の予約のみが応答に返されます。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。 テーブル:場所 [cmn_location]

ヘッダー

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

表 : 34. 要求ヘッダー

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

表 : 35. 応答ヘッダー

ヘッダー	説明
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

ステータスコード

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

表 : 36. ステータスコード

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

応答本文のパラメーター (JSON)

名前	説明
creationDate	予約が作成された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
href	予約の一意の参照リンク。このリンクを別の要求で使用して、予約を取得できます。 データタイプ：文字列
ID	再スケジュールされた予約のSys_id。 データタイプ：文字列 保存場所:予約 [sn_apptmnt_booking_appointment_booking] テーブル
lastUpdate	予約が最後に更新された日時。 データタイプ：文字列 形式:YYYY-MM-DD 00:00:00。例:2025-01-31 09:35:43。
理由	予約を更新する目的。 可能な値： 「予約が再スケジュールされました。」:PATCH メソッドを使用して予約が再スケジュールされました。 「予約 (ID) が正常にキャンセルされました。」:PATCH メソッドを使用して予約がキャンセルされました。 データタイプ：文字列
relatedParty	関連付けられた予約の顧客の詳細。 データタイプ：オブジェクトのアレイ "relatedParty": [ { "@referredType": "String", "id": "String", "name": "String", "role": "String" } ]
relatedParty.id	顧客連絡先のSys_id。 データタイプ：文字列 保存場所:連絡先 [customer_contact] テーブル
relatedParty.name	顧客の連絡先の名前。 データタイプ：文字列
relatedPlace.@referredType	顧客のタイプ。 データタイプ：文字列 可能な値:個々
relatedParty.role	連絡先のロール。 データタイプ：文字列 可能な唯一の値:連絡先
正常終了	要求が成功したかどうかを示すフラグ。 可能な値： true:予約は正常に再スケジュールされました。 false:予約を再スケジュールできませんでした。 データタイプ：ブーリアン

cURL 要求

次の例は、PATCH メソッドを使用して、指定された ID の予約を再スケジュールする方法を示しています。

curl -X POST 'https://instance.service-now.com/api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373cbd ' \ 
-H "Accept: application/json" \ 
-H "Content-Type: application/json" \ 
-u "username":"password" \ 
-data {
  "validFor": { 
      "startDateTime": "2024-07-30 00:0:00", 
      "endDateTime": "2024-08-30 00:00:00" 
              }
  "note": {
      "date": "85388c25b71011104eed4643ae11a993",
      "author": "Sarah Johnson",
      "text": "customer"
    }
  "state": "active"
   }
  ]
}

応答本文には、予約が再スケジュールされたことを示す成功メッセージが表示されます。

{
  "relatedParty": [
    {
      "id": "85388c25b71011104eed4643ae11a993",
      "name": "Sarah Johnson",
      "role": "customer",
      "@referredType": "Individual"
    }
  ],
  "success": true,
  "reason": "Appointment rescheduled!",
  "id": "68cc0a5a9314521060320dd548373cbd",
  "href": "api/sn_tmf_api/appointment/appointment/68cc0a5a9314521060320dd548373cbd",
  "creationDate": "2024-08-30 20:56:54",
  "lastUpdate": "2024-08-30 20:56:54"
}