AWA 手動アサイン API

Zurich API リファレンス

Release

zurich

ft:locale

ja-JP

ft:publication_title

Zurich API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

AWA 手動アサイン API

リリースバージョン: Zurich

更新日 2025年07月31日

所要時間：11分

AWA 手動アサイン API は、利用可能な作業アイテムを利用可能な高度な作業アサイン (AWA) エージェントに手動でアサインするためのエンドポイントを提供します。

作業アイテムは、AWA エージェントによって開始から終了まで処理される 1 件の作業のことです。たとえば、1 件のチャットまたは 1 件のケースは、エージェントにルーティングしてアサインできるオブジェクトになります。詳細については、「高度なワークアサインメント」を参照してください。

この API には高度な作業アサイン (com.glide.awa) プラグインが必要です。この API を呼び出すには、awa_manager ロールまたは awa_integration_user ロールのいずれかが必要です。

AWA 手動アサイン:POST /now/awa/workitems/{work_item_sys_id}/assignments

利用可能な作業アイテムを利用可能な高度な作業アサイン (AWA) エージェントにアサインします。

このエンドポイントの主なユースケースは、外部ルーティングシステムが作業アイテムをルーティングできるようにすることです。外部ルーティングを使用するように高度な作業アサインが構成されている場合、キュー内の作業アイテムは AWAではなく外部ルーティングを使用してアサインされます。このエンドポイントを呼び出すことで、作業アイテムタスクをアサインできます。詳細については、「外部ルーティングの使用」を参照してください。

URL 形式

バージョニングされた URL：/now/{api_version}/awa/workitems/{sys_id}/assignments

デフォルトの URL：/now/awa/workitems/{sys_id}/assignments

注:

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

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

表 : 1. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列
work_item_sys_id	利用可能なエージェントにアサインする作業アイテムの sys_id。作業アイテムは未アサインであり、[受入処理待ち] または [キューに格納] ステータスである必要があります。詳細については、「未割り当てタスク作業項目の確認」を参照してください。データタイプ：文字列テーブル:作業アイテム [awa_work_item]

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

表 : 3. 要求本文パラメーター (XML または JSON)
名前	説明
after_timeout_presence	timeoutパラメーターの有効期限が切れた場合にエージェントが切り替わる在席状況のSys_id。 timeoutパラメーターが渡されない場合、このパラメーターは無視されます。在席状況の詳細については、「 Configure agent presence states」を参照してください。データタイプ：文字列デフォルト:"" (空の文字列) テーブル:AWA 在席状況 [awa_presence_state]
agent_sys_id	必須です。作業アイテムを受け取ることができる利用可能なエージェントの sys_id。エージェントは、awa_agentロールを持つユーザーです。エージェントが対応可能かどうかを判断する方法については、「エージェントの受信ボックスの制御」を参照してください。データタイプ：文字列テーブル：ユーザー [sys_user]
allowed_to_decline	エージェントが作業アイテムを却下できるかどうかを示すフラグ。このパラメーターが `true` の場合、受信ボックスカードには受信ボックスカードの [承認 ] ボタンと [却下 ] ボタンの両方が表示されます。有効な値： true/yes/1:エージェントは作業アイテムを却下できます。 false/no/0:エージェントは作業アイテムを却下できません。データタイプ：ブーリアンデフォルト：true
display_option	作業アイテムが自動的にアサインされたときのカードとタブの表示オプション。このパラメーターは、 enable_auto_assign が `true` として渡された場合にのみ有効です。有効な値： card_and_tab:カードとタブの両方を表示します。 card_only:カードのみを表示します。データタイプ：文字列デフォルト:card_only
enable_auto_assign	作業アイテムを自動的に受け入れるか、エージェントが作業アイテムを手動で受け入れるか却下できるようにするかを示すフラグ。有効な値： true/yes/1:自動的に承認します。 false/no/0:エージェントが手動で承認または却下できるようにします。データタイプ：ブーリアンデフォルト値：false
offered_on	作業アイテムの提供時間。オファー時間は、エージェントが受信ボックス内の作業アイテムを受け入れるために残した残り時間の計算に使用されます。これは、API 要求が処理される時間と、サードパーティのルーティングシステムが API 要求を呼び出す時間との不一致を考慮するのに役立ちます。このパラメーターを使用すると、このエンドポイントを呼び出す外部システムは、作業アイテムの外部システムの内部追跡と同期を維持するように作業アイテムの提供時間を構成できます。たとえば、作業アイテムが 11:30:30 に提供され、タイムアウトが 30 秒で、現在時刻が 11:30:45 の場合、カウントダウンタイマーには 00:15 と表示されます (残り 15 秒と同様)。この値は、作業アイテムの [offered_on] フィールドに保存されます。 timeout パラメーターが渡されない場合、このパラメーターは無視されます。データタイプ：文字列形式:UTC タイムスタンプ (yyyy-MM-dd'T'HH:mm:ss.SSS)
タイムアウト	エージェントがワークアサインメントを承認するのを待機するために、作業アイテムがエージェントの受信ボックスに留まる時間。データタイプ：数値単位：秒

ヘッダー

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

表 : 4. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。デフォルト： application/json
Content-Type	要求本文のデータ形式。サポートされるタイプ：application/json または application/xml。デフォルト： application/json

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

ステータスコード

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

表 : 6. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
401	権限がありません。ユーザー資格情報が間違っているか、渡されていません。
404	見つかりません。要求されたアイテムが見つかりませんでした。
409	競合。指定された作業アイテムまたはエージェントsys_idに関するエラーにより、要求を渡すことができませんでした。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

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


名前	説明
success	手動作業アイテムのアサインが成功したかどうかを示すフラグ。可能な値： true：作業アイテムのアサインに成功しました。 false：作業アイテムのアサインに失敗しました。データタイプ：ブーリアン
メッセージ	成功したアサインまたは例外を確認する応答メッセージ。成功:「手動割り当てが正常に要求されました。」例外：「<work_item_sys_id> は有効な作業アイテムではありません」 – 指定された作業アイテム sys_id が存在しません。「呼び出し元 <API_caller_sys_id> には awa_manager ロールまたは awa_integration_user ロールがありません」 – API 要求を行う認証ユーザーには、awa_manager ロールまたは awa_integration_user ロールのいずれかが必要です。「作業アイテム <work_item_sys_id> をアサインできません」:指定された作業アイテムは [承認済み] または [キャンセル] ステータスであるため、アサインできません。作業アイテムと AWA イベントの確認を参照してください。「<agent_sys_id> は有効なエージェントではありません」 – エージェントに awa_agent ロールがありません。「作業アイテムは既に<agent_sys_id>にアサインされています」:指定された作業アイテムが別のエージェントにアサインされています。「エージェントは利用できません」 – エージェントは AWA で [利用可能] ステータスではありません。エージェントの受信ボックスの制御を参照してください。「タイムアウト値を負の値にすることはできません」:指定したタイムアウト値を負の値にすることはできません。「<presence_state_sys_id> は有効な在席状況ではありません」:指定された在席状況sys_idが AWA 在席状況 [awa_presence_state] テーブルに存在しません。「提供された時間 (<offered_on_timestamp>) は、yyyy-MM-dd'T'HH:mm:ss の形式にする必要があります。SSS" – 指定する offered_on タイムスタンプは、指定された形式である必要があります。「提供された時間 (<offered_on_timestamp >) は現在の時間より前である必要があります。それ以外の場合、エージェントが作業アイテムを受け入れる時間が長くなります」:指定された offered_on タイムスタンプを要求が行われた時間より前にすることはできません。「タイムアウト後のタイムスタンプ (<offered_on_timestamp >) は現在時刻より後である必要があります。それ以外の場合、エージェントには作業アイテムを受け入れる時間がありません」:指定された offered_on タイムスタンプにタイムアウト値を加算した後のタイムスタンプは、要求が行われた時刻より後である必要があります。「<display_option> は有効な表示オプションではありません」:指定display_option、「card_only」または「card_and_tab」のいずれかの値である必要があります "%s is not a valid boolean value" – 指定するブール型値は、"yes"/"no"、"true"/"false"、"1"/"0" のいずれかのブール形式である必要があります。データタイプ：文字列

cURL 要求

次の例は、必須パラメーターのみを使用して、利用可能な AWA エージェントに作業アイテムをアサインする方法を示しています。

curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"agent_sys_id\":\"<agent_sys_id>\"}" \
--user 'username':'password'

結果は、タスクがエージェントに正常にアサインされたことを示しています。作業アイテム [awa_work_item] テーブルの [アサイン先] フィールドで結果を確認できます。

{
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}

cURL 要求

次の例は、オプションのパラメーターを含めて、利用可能な AWA エージェントに作業アイテムをアサインする方法を示しています。

curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{
    "agent_sys_id": "46d44a23a9fe19810012d100cca80666",
    "timeout":"10",
    "offered_on":"2024-04-03T23:09:31.000"
  }'
--user 'username':'password'

{
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}