メニュー

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

REST API: TaskQueues

TaskQueues are the resource you use to categorize Tasks and describe which Workers are eligible to handle those Tasks. As your Workflows process Tasks, those Tasks will pass through one or more TaskQueues until the Task is assigned and accepted by an eligible Worker. TargetWorkers expressions, described below, control which Workers are eligible to receive Tasks from a given TaskQueue.

Task割り当て優先度

TaskQueueは、TaskQueueの TargetWorkers 条件を満たす「available」なActivityに存在するWorkerにTaskを割り当てます。 Taskは、次の順番で割り当てられます。

  • 優先度の高いTaskが常に優先度の低いTaskより先に割り当てられます。低い優先度のTaskの有効期限は無視されます。
  • 同じ優先度のTaskの中では、常に、最も古いTaskが最初に割り当てられます。

TaskQueuesとActivities

In a multitasking Workspace, a Worker's status does not change as they are assigned and complete Tasks. A Worker's ability to accept a new Task is informed by their active capacity. For single-tasking Workspaces, a Worker is available for a Task based on their activity status. The AssignmentActivitySid and ReservationActivitySid properties can be used to control a Worker's availability during assignment.

When a TaskQueue reserves a Worker for a Task, it places the Worker in the ReservationActivitySid status. If the Worker accepts the Task, the Worker is placed in the AssignmentActivitySid status.

Note that in a single-tasking Workspace, when a Task completes, the Worker's activity does not change. This is because whether or not a Task's completion should change a Worker's activity is dependent on the workflow—the system needs confirmation of the Worker's availability before it will assign Tasks to them again. If this is the experience you want, the easiest way to achieve this is to capture the "task.completed" event and issue an update to the associated Worker's activity at that point.

アクション


全TaskQueueを一覧する

リソースURI

GET /v1/Workspaces/{WorkspaceSid}/TaskQueues

{WorkspaceSid} で指定されるWorkspace内のTaskQueueの一覧を返します。

Workspaceに存在する すべてのTaskQueueを一覧する

        
        
        
        

        リストフィルター

        下記のGETのクエリー文字列パラメーターを使用すると、返される一覧を制限することができます。 パラメーターは大文字と小文字を区別することに注意してください:

        フィールド 概要
        FriendlyName TaskQueueの、人間が読みやすい形式の説明(例: 「Customer Support」、「2014 Election Campaign」)でフィルタリングします。
        EvaluateWorkerAttributes Worker属性Expressionを提供します。このExpressionは、これらの属性を持つWorkerにTaskを割り当てるTaskQueueの一覧を返します。

        メモ: 既定では、最初の50のTaskQueueが返されます。 それよりも多くのTaskQueueを取得する場合は、PageSizeパラメーターを指定してください。 詳細については、「ページ情報」を参照してください。


        TaskQueueの作成

        リソースURI

        POST /v1/Workspaces/{WorkspaceSid}/TaskQueues
        

        新しいTaskQueue を作成します。

        新しいTaskQueueを作成する例

              
              
              
              
              必須パラメーター
              フィールド 概要
              FriendlyName Human readable description of this TaskQueue (for example “Support – Tier 1”, “Sales” or “Escalation”) (📇 PII )
              ReservationActivitySid ActivitySID to assign workers once a task is reserved for them (🏢 not PII )
              AssignmentActivitySid ActivitySID to assign workers once a task is assigned for them (🏢 not PII )
              オプションパラメーター
              フィールド 概要
              TargetWorkers A string describing the Worker selection criteria for any Tasks that enter this TaskQueue. For example '"language" == "spanish"'. Additional details on Workers expressions below. Defaults to 1==1. (🏢 not PII )
              MaxReservedWorkers The maximum amount of workers to create reservations for the assignment of a task while in this queue. Defaults to 1, with a Maximum of 50. (🏢 not PII )
              TaskOrder TaskOrder will determine which order the Tasks will be assigned to Workers. Set this parameter to LIFO to assign most recently created Task first or FIFO to assign the oldest Task. Default is FIFO. Click here to learn more. (🏢 not PII )

              メモ: Workerの取りうるTaskQueuesの最大値は5,000です。 それ以上が必要な場合は、お問い合わせください。

              TargetWorkers:Worker選択条件の記述

              Workerのアイデンティティーに個人識別情報を使用しないでください

              Using TargetWorkers, you can target individual Workers. You should not use directly identifying information (aka personally identifiable information or PII) like a person's name, home address, email or phone number, etc., because the systems that will process these Queues assume there is no directly identifying information within the TargetWorkers expression.

              Instead, you should use a GUID or other pseudonymized identifier for Worker identity. You can read more about how we process your data in our privacy policy.

              TaskRouterは、TaskQueueの TargetWorkers Expressionを使用して、WorkerをTaskQueueにバインドします。 TargetWorkersは、SQLライクなExpression構文を使用して、Workspace内のWorkerをフィルタリングします。

              たとえば、2人のエージェントが存在するとします。 1人目のWorkerであるAliceは、英語を話し、サポートとセールスのTaskを処理します。 これは、次の属性によってモデル化されます。

              '{ "skills": ["support", "sales"], "languages":["english"]}'

              2人目のWorkerであるBobは、セールスリクエストのみ処理し、スペイン語と英語を話します。

              '{"skills": ["sales"], "languages": ["spanish", "english"]}'

              これらのWorkerが存在する場合、英語を話し、サポートスキルを持つWorkerにのみ通話をルーティングするように、TargetWorkers Expressionを記述できます。

              (skills HAS "support") AND (languages HAS "english")'

              このTaskQueueからTaskを承諾するのはAliceのみです。もう1つTaskQueueを作成し、スペイン語を話すスキルを持つWorkerに通話をルーティングするように TargetWorkers Expressionを記述できます。

              (languages HAS "spanish")'

              この場合はBobのみがこのTaskQueueからTaskを受諾します。

              TaskQueueの作成

              上述の TargetWorkers Expressionを使用してTaskQueueを作成するには、次のリクエストを送信します。

              英語サポートのTaskQueueの場合:

              curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues  \
              -d FriendlyName=EnglishSupport \
              -d TargetWorkers='(skills HAS "support") AND (languages HAS "english")' \
              -d AssignmentActivitySid={ActivitySid}
              -d ReservationActivitySid={ActivitySid}
              -u {AccountSid}:{AuthToken}
              

              スペイン語のTaskQueueの場合:

              curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues  \
              -d FriendlyName=SpanishDefault \
              -d TargetWorkers='(languages HAS "spanish")' \
              -d AssignmentActivitySid={ActivitySid}
              -d ReservationActivitySid={ActivitySid}
              -u {AccountSid}:{AuthToken}
              

              Workerに特定のスキルにおける各自の専門知識を表す整数値が割り当てられるスキルベースの割り当てモデルも使用できます。 次に、'tech_support_skill' 属性に基づいて最高のWorkerを選択するスキルベースのルーティングを使用するTaskQueueを作成する例を示します。

              curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues  \
              -d FriendlyName="Tech Support – Tier 1" \
              -d TargetWorkers="tech_support_skill < 5" \
              -d AssignmentActivitySid={ActivitySid}
              -d ReservationActivitySid={ActivitySid}
              -u {AccountSid}:{AuthToken}
              


              curl https://taskrouter.twilio.com/v1//Workspaces/{WorkspaceSid}/TaskQueues \
              –d FriendlyName="Tech Support - Escalation" \
              –d TargetWorkers="tech_support_skill > 5" \
              -d AssignmentActivitySid={ActivitySid}
              -d ReservationActivitySid={ActivitySid}
              -u {AccountSid}:{AuthToken}
              

              任意のWorkerにTaskを割り当てるには、常にtrueに評価されるExpressionを指定します。

              curl https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues \
              –d FriendlyName="Everyone" \
              –d TargetWorkers="1==1" \
              -u {AccountSid}:{AuthToken}
              TargetWorkers: Supported operators
              

              Workerの属性の評価

              TaskQueueのリストリソースの EvaluateWorkerAttributes パラメーターを使って、指定された TargetWorkers Expressionに一致するWorkerを表示できます。

              次の例は、どのTaskQueueが tech_support_skill 属性が 6 であるWorkerにマッピングされるかをチェックする方法を示します。 上述の例で言えば、これは "Tech Support – Escalation" Queueにマッピングされるはずです。

              curl –XGET https://taskrouter.twilio.com/v1/Workspaces/{WorkspaceSid}/TaskQueues \
              --data-urlencode EvaluateWorkerAttributes='{"tech_support_skill": "6"}'
              -u {AccountSid}:{AuthToken}
              

              TargetWorkers の演算子

              TargetWorkers Expressionで次の演算子を使うことができます。

              • 等号:===
              • 不等号: !=
              • より大きい: >
              • より小さい: <
              • 以上: >=
              • 以下: <=
              • カッコ(演算子の優先度を示す): ( )
              • 角カッコ(リスト/配列を示す): [ ]
              • HAS, >-。比較式の左辺のWorker属性の値にExpressionの右辺の文字列が含まれるかどうか判断します。
              • IN, <-。Expressionの左辺のWorker属性の値が右辺のリストに * 含まれるかどうか判断します。
              • AND - 左辺と右辺のサブExpressionが両方とも true の場合、true として解決されます。それ以外の場合は false として解決されます。
              • OR - 左辺と右辺のサブExpressionの一方または両方とも true の場合、true として解決されます。それ以外の場合は false として解決されます。

              複数Reservation

              特定のQueueにTaskが入ったときに一連のWorkerのReservationを作成する機能を要求されることがよくあります。 QueueのMaxReservedWorkersパラメーターを構成することによって、まさにその機能を実行できます。 WorkflowによってTaskが特定のQueueにルーティングされると、TaskRouterは、使用可能なすべてのWorkerのReservationを、MaxReservedWorkersパラメーターの値を上限として作成します。 いずれかのWorkerがそのTaskのReservationを承諾すると、他のすべてのReservationは撤回されます。 撤回されたReservationを承諾しようとすると、410番台のレスポンスを受信します。これは、指定されたReservationを使用してTaskのReservationを承諾することはできなくなったことを示します。

              たとえば、次のようになります。

              あるTaskが "Tech Support - Escalation" TaskQueueにエスカレートされます。このTaskQueueでは、2人のWorkerが使用可能であり、MaxReservedWorkersパラメーターは5に構成されています。 WorkerごとにReservationが作成されるので、合計で2つのReservationが作成されます。 Reservationごとに割り当てコールバックが作成されます。 Reservation作成のたびに、Eventコールバックが作成されます。

              ここで、Worker 1がこのReservationを承諾します。 Worker 2は、EventCallbackUrlとJS SDKを通じて、割り当てられていたReservationが撤回されたことを示す通知を受信します。


              TaskQueueを取得する

              リソースURI

              GET /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}
              

              Return a single TaskQueue resource identified by {TaskQueueSid} で識別される一つのTaskQueueリソースを返します

              Example for retreiving a single TaskQueue from a workspace

                    
                    
                    
                    

                    リソースのプロパティ

                    TaskQueue インスタンスリソースは、次のプロパティーで表されます。

                    フィールド 概要
                    Sid TaskQueueの一意なIDです。
                    AccountSid このTaskQueueを所有するアカウントのIDです。
                    WorkspaceSid このTaskQueueを所有するWorkspaceのIDです。
                    FriendlyName TaskQueueの、人間が読みやすい形式の説明(例: 「Customer Support」、「Sales」)です。
                    TargetWorkers このTaskQueueに関連付けられているWorker選択Expressionです。
                    ReservationActivitySid このTaskQueueのTaskに予約されたWorkerに割り当てられるActivityです。 初期値は「Reserved for Task」です。
                    AssignmentActivitySid このTaskQueueのTaskを受諾したWorkerに割り当てられるActivityです。 既定値は「Unavailable for Assignment」です。
                    MaxReservedWorkers このQueueに入っているTaskの割り当てReservationを作成するWorkerの最大数です。

                    TaskQueueを更新する

                    リソースURI

                    POST /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}
                    

                    TaskQueueを変更します。 TaskQueueを変更し、そのTargetWorkers Expressionを修正した場合、新しいTargetWorkersに合わせて、このTaskQueueに関連付けられているWorker統計がリセットされます。このTaskQueueのTask統計は変更されません。

                    TaskQueueを更新する例

                          
                          
                          
                          
                          POSTパラメーター

                          TaskQueueを変更する際、次のパラメーターをPOSTできます。

                          パラメーター 概要
                          FriendlyName Human readable description of this TaskQueue (for example “Support – Tier 1”, “Sales” or “Escalation”) (📇 PII )
                          TargetWorkers A string describing the Worker selection criteria for any Tasks that enter this TaskQueue. For example '"language" == "spanish"' If no TargetWorkers parameter is provided, Tasks will wait in this queue until they are either deleted or moved to another queue. Additional examples on how to describing Worker selection criteria below. (🏢 not PII )
                          ReservationActivitySid ActivitySID that will be assigned to Workers when they are reserved for a task from this TaskQueue. (🏢 not PII )
                          AssignmentActivitySid ActivitySID that will be assigned to Workers when they are assigned a task from this TaskQueue. (🏢 not PII )
                          MaxReservedWorkers The maximum amount of workers to create reservations for the assignment of a task while in this queue. Maximum of 50. (🏢 not PII )
                          TaskOrder TaskOrder will determine which order the Tasks will be assigned to Workers. Set this parameter to LIFO to assign most recently created Task first or FIFO to assign the oldest Task. Default is FIFO. Click here to learn more. (🏢 not PII )

                          TaskQueueを削除する

                          リソースURI

                          DELETE /v1/Workspaces/{WorkspaceSid}/TaskQueues/{TaskQueueSid}
                          

                          Removes the TaskQueue identified by {TaskQueueSid}

                          TaskQueueを削除する例

                                
                                
                                
                                
                                Rate this page:

                                ヘルプが必要ですか?

                                We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.