Method: scheduling.solveShiftScheduling

將員工指派到輪班，藉此將員工的排程偏好設定最大化，並將違反排程限制的情形降到最低，藉此解決指定 SolveShiftSchedulingRequest 的輪班安排問題。

HTTP 要求

POST https://optimization.googleapis.com/v1/scheduling:solveShiftScheduling

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "requestId": string,
  "solveParameters": {
    object (SolveParameters)
  },
  "employees": [
    {
      object (Employee)
    }
  ],
  "shifts": [
    {
      object (Shift)
    }
  ],
  "coverageRequirements": [
    {
      object (CoverageRequirement)
    }
  ],
  "roleIds": [
    string
  ],
  "skillIds": [
    string
  ],
  "locationIds": [
    string
  ],
  "budgetRequirements": [
    {
      object (BudgetRequirement)
    }
  ],
  "assignmentsHint": [
    {
      object (ShiftAssignment)
    }
  ]
}
欄位
requestId

string

問題或要求 ID。
solveParameters

object (SolveParameters)

用於控制問題單一解題的參數。
employees[]

object (Employee)

所有有空的員工都已排定時程。
shifts[]

object (Shift)

所有調節都會形成時間表。
coverageRequirements[]

object (CoverageRequirement)

整個規劃期間的涵蓋率規定。這些標籤會指出必須在特定時間範圍內或輪班 ID 清單內，完成每個角色或具備技能的員工人數。所有涵蓋範圍要求都必須以時段或轉移 ID 清單 (但請勿兩者並用) 指定。每個地點的涵蓋範圍規定的時間範圍不得重疊。這些限制的預設優先等級為角色需求 PRIORITY_MANDATORY，對技能需求則為 PRIORITY_LOW。詳情請參閱 Priority 列舉。
roleIds[]

string

整個員工的所有可能角色清單。每位員工都必須至少指派一個角色，做為輪班對象。角色是指輪班期間特定的工作指派，例如註冊的護理師、執行主管、服務生等。員工指派給輪班時，也會分派到單一特定角色。
skillIds[]

string

公司內所有可能具備的技能清單。「技能」是指員工可能會取得與指派工作無關的其他資格認證，例如認證、使用語言等。這份清單可以空白。員工若指派給輪班，就必須滿足輪值班上所有必要的技能。
locationIds[]

string

此清單列出了時間表中輪班的所有可能位置。這份清單可以空白。指定不同地點就能派上用場。舉例來說，如果有護理師想為醫院的多名護理師安排時間，或是飯店經理想為多間飯店安排員工，指定不同地點即可。
budgetRequirements[]

object (BudgetRequirement)

排程問題的預算規格。這些規定的預設優先等級為 PRIORITY_LOW。詳情請參閱 Priority 列舉。
assignmentsHint[]

object (ShiftAssignment)

轉移指派作業，做為安排時間問題的暫定解決方案 (又稱解決方案提示)。如果指派作業與無法指派的 shift 或排程要求衝突，系統就會忽略作業提示。

回應主體

針對工作團隊排程 API 的回應。如果傳回的 solutionStatus 是 NOT_SOLVED_DEADLINE_EXCEEDED 或 INFEASIBLE，每個回應的 shiftAssignments 就會是空白的。如果傳回的 solutionStatus 是 OPTIMAL 或 FEASIBLE，則 shiftAssignments 會傳回有效的轉移指派。如果是有效的班表指派，包含下列屬性：

  1. 每個員工 ID 都包含在要求中所指定的員工組中。
  2. 指派給員工的每個角色 ID 都包含在該員工的一組角色 ID 中。
  3. 每個轉移 ID 都包含在要求中指定的一組轉移組中。
  4. 每個班表 ID 都不是該員工無法指派的班表 ID。
  5. 我們不會將員工指派給兩組重疊的輪班，
  6. 根據指定的排程，沒有違反任何優先順序等級或優先順序為 PRIORITY_MANDATORY 的要求。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "requestId": string,
  "solutionStatus": enum (SolutionStatus),
  "shiftAssignments": [
    {
      object (ShiftAssignment)
    }
  ],
  "statusMessage": string
}
欄位
requestId

string

與此回應相關聯的要求 ID。
solutionStatus

enum (SolutionStatus)

已傳回解決方案的狀態。如果解決方案不是 FEASIBLE 或 OPTIMAL，這個原型中的其他欄位可能空白。如果狀態為「NOT_SOLVED_DEADLINE_EXCEEDED」，表示已達時間限制，而且並未找出可行的解決方案，或判定解決方案是否可行。如果無法滿足優先等級的 MANDATORY 限制，要求可能無法執行。
shiftAssignments[]

object (ShiftAssignment)

所有作業的清單。每個 ShiftAssignment 都會指定員工、輪班指派對象，以及在該輪班中獲派的角色。
statusMessage

string

如果 solutionStatus 不是最佳值，這個欄位可能包含解題工具的其他資訊。

SolveParameters

用於控制輪班時間安排問題的單一解決方式。

JSON 表示法 
{
  "timeLimit": string
}
欄位
timeLimit

string (Duration format)

解題工具應花費多少時間處理問題。如果未設定，預設值為 1 分鐘。

這個值並非硬性限制，也不會影響通訊費用。解決問題的預期延遲時間可能會稍微超過這個值。

時間長度以秒為單位，最多可有 9 個小數位數，並結尾為「s」。例如："3.5s"。

員工

正為所需職員的員工。

JSON 表示法 
{
  "id": string,
  "roleIds": [
    string
  ],
  "skillIds": [
    string
  ],
  "shiftPreferences": [
    {
      object (ShiftPreference)
    }
  ],
  "schedulingConstraints": [
    {
      object (SchedulingConstraint)
    }
  ],
  "resourceConstraints": [
    {
      object (ResourceConstraint)
    }
  ],
  "shiftRequests": [
    {
      object (ShiftRequest)
    }
  ],
  "hourlyContract": {
    object (HourlyContract)
  }
}
欄位
id

string

指派給這位員工的專屬 ID。
roleIds[]

string

這位員工可執行的角色 ID。至少須指定一個角色。員工指派給輪班時，也會指派給這份清單中的一個角色。在排程期間，系統可能會將員工指派給不同的角色。
skillIds[]

string

這位員工擁有的技能 ID。這份清單可以空白。員工派遣到輪班後，他們會使用此處列出的任一技巧，在指派值期間涵蓋應有的技能需求。
shiftPreferences[]

object (ShiftPreference)

員工的輪班偏好。這裡指定的班移代表在排程期間替員工分配的輪班。shiftPreferences 中指定的偏移 ID 不得重複。解題工具會嘗試盡量提高所有符合的 shiftPreferences 中的 ShiftPreference.preference 值總和。
schedulingConstraints[]

object (SchedulingConstraint)

此員工的排程限制清單。這些限制的預設優先等級為 PRIORITY_MEDIUM。詳情請參閱 Priority 列舉。
resourceConstraints[]

object (ResourceConstraint)

你可以將 schedulingConstraints 中未指定的其他排程限制新增至 resourceConstraints。ResourceConstraint 則是限制員工資源的抽象表示法。這些限制的預設優先等級為 PRIORITY_MEDIUM。詳情請參閱 Priority 列舉。
shiftRequests[]

object (ShiftRequest)

員工輪班要求清單。要求可以是指派員工，也可以不指派給特定輪班。對員工的所有固定排程指派都能以 ShiftRequest 表示，優先順序為 PRIORITY_MANDATORY。這位員工最多只能在一個排程要求中出現輪班 ID。這些要求的預設優先等級為 PRIORITY_LOW。詳情請參閱 Priority 列舉。
hourlyContract

object (HourlyContract)

指定員工的定期和加班率的合約。

ShiftPreference

特定位移 ID 的數值偏好設定。

JSON 表示法 
{
  "shiftId": string,
  "preference": integer
}
欄位
shiftId

string

指定偏好設定的 Shift ID。
preference

integer

偏好程度的值越大，代表偏移量越理想。

SchedulingConstraint

特定員工適用的排程限制。指定限制只會在指定的時間間隔 [startDateTime, endDateTime) 套用。

JSON 表示法 
{
  "priority": enum (Priority),
  "startDateTime": {
    object (DateTime)
  },
  "endDateTime": {
    object (DateTime)
  },

  // Union field type can be only one of the following:
  "minimumMinutes": integer,
  "maximumMinutes": integer,
  "minimumConsecutiveWorkDays": integer,
  "maximumConsecutiveWorkDays": integer,
  "minimumShiftCount": integer,
  "maximumShiftCount": integer,
  "minimumRestMinutes": integer
  // End of list of possible types for union field type.
}
欄位
priority

enum (Priority)

這項排程限制的優先順序等級。所有排程限制的預設優先順序為 PRIORITY_MEDIUM。
startDateTime

object (DateTime)

套用這項排程限制的開始時間 (含)。
endDateTime

object (DateTime)

套用這項排程限制的結束時間 (不含)。
聯集欄位 type。要指定的限制類型。每項限制都只會在上方指定時間範圍內套用。type 只能是下列其中一項：
minimumMinutes

integer

員工可工作的最低工作分鐘數。如果員工獲派的輪班與時間重疊 (全部或部分) 重疊，則該值將計入該時間範圍重疊的分鐘數。
maximumMinutes

integer

員工在時間範圍內的工作時間上限。如果員工獲派的輪班與時間重疊 (全部或部分) 重疊，則該值將計入該時間範圍重疊的分鐘數。
minimumConsecutiveWorkDays

integer

員工可連續工作的天數下限。如果員工指派給指定日當天開始輪班，則員工在特定日期工作。指派給員工在這段時間內開始的任何班機都會列入計算。
maximumConsecutiveWorkDays

integer

員工可連續工作的天數上限。如果員工指派給指定日當天開始輪班，則員工在特定日期工作。指派給員工在這段時間內開始的任何班機都會列入計算。
minimumShiftCount

integer

員工可以工作的最低輪班次數。指派給該員工的所有輪班時間與該時段重疊時，都會列入計算。
maximumShiftCount

integer

員工可安排的輪班時數上限。指派給該員工的所有輪班時間與該時段重疊時，都會列入計算。
minimumRestMinutes

integer

員工在輪班結束後必須休息至少時間 (分鐘)，才會指派給其他輪班。這項限制會套用到完全包含在 [startDateTime、endDateTime] 中的轉乘。

優先順序

員工時間表或服務涵蓋範圍限制的優先順序等級。包括 SchedulingConstraint、ResourceConstraint、ShiftRequest 和 CoverageRequirement。由於限制之間可能會有衝突，因此無法保證能滿足每項限制。因此，每種類型的限制都有優先順序 (由使用者指定或預設值)，讓解題工具瞭解針對完整排程的所有限制條件的相對重要性。

列舉
PRIORITY_UNSPECIFIED 優先順序等級不明。
PRIORITY_LOW 優先順序最低。此優先順序的限制較不重要。如果找不到可行的解決方案，則會優先考量違規行為。
PRIORITY_MEDIUM 優先順序等級中等。設有此優先順序的限制比具有 PRIORITY_LOW 優先順序的限制更重要，但重要性低於 PRIORITY_HIGH 優先順序的限制。如果在放寬 PRIORITY_LOW 優先順序的所有限制後找不到可行的解決方案，則接下來會考慮 PRIORITY_MEDIUM 優先順序的限制條件。
PRIORITY_HIGH 優先順序最高。此優先順序等級的限制最為重要。如果在降低優先順序較低的層級之後找不到可行的解決方案，則這些事件最後會視為違規。
PRIORITY_MANDATORY 代表解題工具無法違反的優先等級。如果解題工具傳回 SolutionStatus.INFEASIBLE，可能是因為 PRIORITY_MANDATORY 限制過多。

ResourceConstraint

通用限制，可限制員工使用的特定「資源」量。這是更特定 SchedulingConstraint 的抽象版本，對使用者而言更具彈性。你可以使用這則訊息指定許多無法在 SchedulingConstraint.type 中指定的排程限制。

JSON 表示法 
{
  "priority": enum (Priority),
  "resourceUsages": {
    string: number,
    ...
  },
  "minimumResourceUsage": number,
  "maximumResourceUsage": number
}
欄位
priority

enum (Priority)

這項資源限制的優先順序等級。所有資源限制的預設優先順序為 PRIORITY_MEDIUM。
resourceUsages

map (key: string, value: number)

偏移使用的資源量。舉例來說，如果這項限制適用於員工在特定週所工作的最低和最高時數，這張地圖就會顯示當週發生的輪班時間和每次調整的時數。

這個物件中包含 "key": value 組合的清單，例如：{ "name": "wrench", "mass": "1.3kg", "count": "3" }.
minimumResourceUsage

number

符合資源限制的最低資源用量。
maximumResourceUsage

number

符合資源限制的最大資源用量。

ShiftRequest

員工的要求指定或未指派給特定輪班。

JSON 表示法 
{
  "priority": enum (Priority),
  "shiftIds": [
    string
  ],
  "type": enum (WorkStatus)
}
欄位
priority

enum (Priority)

此排程要求的優先順序等級。所有排程要求的預設優先順序為 PRIORITY_LOW。
shiftIds[]

string

排程要求的轉移 ID。
type

enum (WorkStatus)

要求類型，例如是否指派或未指派給移轉集。

WorkStatus

員工是否在工作。

列舉
WORK_STATUS_UNSPECIFIED 工作狀態不明。
STATUS_WORK 代表工作人員的狀態。
STATUS_NOT_WORK 代表員工的狀態 (沒有工作)。

HourlyContract

指定基本每小時收費、分差和加班倍數，以決定員工的報酬。注意不同地區的法規可能需要不同的超額補償計算。解題工具可估算出差額的補償額，藉此降低總成本或達到預算 (請參閱 BudgetRequirement)。但並非用來計算薪資。

JSON 表示法 
{
  "baseHourlyRate": number,
  "hourlyRateShiftDifferentials": {
    string: number,
    ...
  },
  "overtimePeriods": [
    {
      object (OvertimePeriod)
    }
  ]
}
欄位
baseHourlyRate

number

非加班工作的報酬。如果員工適用多種費率，系統會根據此基本每小時費率套用不同的費率。此外，如果有多個房價，基本每小時費率應是這些費率的最低價格。
hourlyRateShiftDifferentials

map (key: string, value: number)

每小時費率差異，根據 baseHourlyRate 支付。舉例來說，如果基本每小時費率為每小時 $30 美元，「shift_1」費用為每小時 $40 美元，「shift_2」是以每小時 $45 美元的費率支付，那麼 proto 表示法為：baseHourlyRate: 30 hourlyRateShiftDifferentials {key: "shift_1" value: 10} hourlyRateShiftDifferentials {key: "shift_2" value: 15}。

這個物件中包含 "key": value 組合的清單，例如：{ "name": "wrench", "mass": "1.3kg", "count": "3" }.
overtimePeriods[]

object (OvertimePeriod)

需要計算各時期的長期清單。期間不得重疊。

OvertimePeriod

固定且定期 (通常為 168 小時或七個連續 24 小時的期間) 的週期，用於判斷超額薪酬。每個時段都會有延長賽程 (例如1.5) 相對於 baseHourlyRate，以及可視為一般 (非加班) 作業的小時數限制。任何與「startDateTime」(含) 和「endDateTime」(不含) 時間範圍重疊的任何轉變都會計入該時間範圍工作的總時數。如果重疊部分的時間重疊，系統只會計入重疊的時數。

JSON 表示法 
{
  "overtimeMultiplier": number,
  "startDateTime": {
    object (DateTime)
  },
  "endDateTime": {
    object (DateTime)
  },
  "maximumRegularHours": number
}
欄位
overtimeMultiplier

number

計算每小時匯率的調節係數 (必須大於或等於 1.0)。加時每小時費率通常會以 baseHourlyRate * overtimeMultiplier 計算。如果透過 hourlyRateShiftDifferentials 提供多個速率，解題工具會使用簡易的計時期間適用的平均比率，近似於時速的每小時比率。注意：不同地區的法規可能需要不同的超額補償計算。解題工具可估算出於某種程度的補償金，以降低總費用的代理量或達到預算，但不作為運算薪資工具。
startDateTime

object (DateTime)

延長期間的開始時間。如果這次轉變與時間重疊，系統會從 startDateTime 計算這類轉變的時數。
endDateTime

object (DateTime)

延長期間的結束時間。如果這次偏移有重疊情形，則累計的時間不會超過 endDateTime。
maximumRegularHours

number

按一般 (非加班) 費率支付的工作時數上限。這個數量必須為正數。

Shift

輪班是指員工可在特定時間範圍內工作。

JSON 表示法 
{
  "id": string,
  "locationId": string,
  "startDateTime": {
    object (DateTime)
  },
  "endDateTime": {
    object (DateTime)
  },
  "breakRules": [
    {
      object (BreakRule)
    }
  ]
}
欄位
id

string

指派給這個位移的專屬 ID。
locationId

string

此次調整作業的地區 ID。這個欄位可以留空。
startDateTime

object (DateTime)

偏移的開始時間 (含)。
endDateTime

object (DateTime)

偏移的結束時間 (不含)。目前解題工具僅允許移動少於 24 小時的位移。
breakRules[]

object (BreakRule)

偏移期間發生的中斷規則清單。執行這項轉變的員工會在每 break_rule指派休息時間，在此期間，他們無法涵蓋自己擔任的角色所需的工作。每個 BreakRule 個時間範圍都必須完整納入這個偏移的時間範圍內。

BreakRule

決定休息時間與時間長度內的規則。這裡會列出所有考量到的可能廣告插播，以 ruleIncrementMinutes 為單位遞增。舉例來說，如果斷行規則是模擬從 10:00 開始到 11:00 的 30 分鐘休息時間，規則的遞增單位是 20 分鐘，則系統會視為 [10:00, 10:30]、[10:20, 10:50]、[10:40, 10:10]、[10:40, 11:10]

JSON 表示法 
{
  "earliestStartTime": {
    object (DateTime)
  },
  "latestStartTime": {
    object (DateTime)
  },
  "durationMinutes": integer,
  "ruleIncrementMinutes": integer
}
欄位
earliestStartTime

object (DateTime)

廣告插播的最早開始時間 (含)。只能設定 hours 和 minutes。
latestStartTime

object (DateTime)

廣告插播的最晚開始時間 (含)。只能設定 hours 和 minutes。
durationMinutes

integer

廣告插播的時間長度 (以分鐘為單位)。
ruleIncrementMinutes

integer

[選用] 此廣告插播規則可考慮的所有廣告插播時間點 (以分鐘為單位)。如果沒有設定，預設值為 durationMinutes。

CoverageRequirement

工作地點要求可指定特定時間範圍和地點內，一組角色和/或技能所需的員工人數。特定位置的 DateTime 間隔不得重疊。或者，您也可以提供偏移 ID 清單，而不是時間範圍和地點。只有能獲派特定角色 (或具備特定技能) 的員工，才符合這項規定。

就特定職務和/或技能而言，符合以下條件時，至少須有 targetEmployeeCount 名員工在時間範圍內 (或shiftIds內每輪班) 工作，滿足員工的涵蓋率要求。相反地，如果時間範圍內的任一時間點 (或 shiftIds 班班制班) 的員工人數少於 targetEmployeeCount 人，即不符合保固範圍要求。仍有超過 targetEmployeeCount 的員工仍符合要求，但解題工具已盡可能減少員工的工作量。

JSON 表示法 
{
  "startDateTime": {
    object (DateTime)
  },
  "endDateTime": {
    object (DateTime)
  },
  "locationId": string,
  "shiftIds": [
    string
  ],
  "roleRequirements": [
    {
      object (RoleRequirement)
    }
  ],
  "skillRequirements": [
    {
      object (SkillRequirement)
    }
  ]
}
欄位
startDateTime

object (DateTime)

涵蓋率規定的開始時間 (含)。如要設定，shiftIds 必須留空。
endDateTime

object (DateTime)

涵蓋率規定的結束時間 (不含)。如要設定，shiftIds 必須留空。
locationId

string

需要員工的位置。shiftIds 並非空白，這個欄位必須留空。
shiftIds[]

string

如有設定，角色和技能需求將分別套用至這份清單中的每個班表 ID。如果 shiftId 不是空白，則 startDateTime、endDateTime 和 locationId 必須留空。
roleRequirements[]

object (RoleRequirement)

於時間範圍內需要指派給指定角色的員工人數。每個角色 ID 最多只能提供一個 role_requirement。每項規定的預設優先等級為 PRIORITY_MANDATORY。如果在這段期間任何時間點指派給指定角色的員工少於 targetEmployeeCount 位，就違反了這些限制。
skillRequirements[]

object (SkillRequirement)

在這段時間內，具有指定技能的員工人數需求，且必須指派給輪值班。每個技能 ID 最多只能提供一個 skill_requirement。每項規定的預設優先等級為 PRIORITY_LOW。如果在指定時間範圍內，擁有特定技能的員工人數少於 targetEmployeeCount 人，則違反這些限制。

RoleRequirement

於時間範圍內需要指派給指定角色的員工人數。

JSON 表示法 
{
  "roleId": string,
  "targetEmployeeCount": integer,
  "priority": enum (Priority)
}
欄位
roleId

string

需求的角色 ID。
targetEmployeeCount

integer

在指定時間範圍內，指派給該角色的員工人數。
priority

enum (Priority)

這項需求限制的優先等級。所有資源限制的預設優先順序為 PRIORITY_MANDATORY。

SkillRequirement

在指定時間範圍內工作且具備指定技能的員工人數。

JSON 表示法 
{
  "skillId": string,
  "targetEmployeeCount": integer,
  "priority": enum (Priority)
}
欄位
skillId

string

需求的技能 ID。
targetEmployeeCount

integer

在指定時間範圍內，具有特定技能的員工人數。
priority

enum (Priority)

這項需求限制的優先等級。所有資源限制的預設優先順序為 PRIORITY_LOW。

BudgetRequirement

指定時間間隔的預算需求。

JSON 表示法 
{
  "totalBudget": number,
  "startDateTime": {
    object (DateTime)
  },
  "endDateTime": {
    object (DateTime)
  },
  "priority": enum (Priority)
}
欄位
totalBudget

number

指定時間間隔的總預算。如果優先順序為 PRIORITY_MANDATORY，則必須指定總預算。

如未設定 totalBudget，系統會根據指定的 priority 盡可能降低排程的總費用。舉例來說，如果預算的 priority 為 PRIORITY_MEDIUM，則解題工具會先將成本降到最低，再減少優先順序為 PRIORITY_LOW 的限制違規事項。
startDateTime

object (DateTime)

套用這項預算的開始時間。如果未指定開始時間，則系統會將該時間設為所有輪班時間的最早開始時間。
endDateTime

object (DateTime)

這項預算套用期間的結束時間。如果未指定結束時間，則系統會將該時間設為所有輪班時間的最晚結束時間。
priority

enum (Priority)

在指定時間範圍內達到預算要求的優先順序層級。預設優先順序為 PRIORITY_LOW。如果將優先順序設為 PRIORITY_MANDATORY，就必須設定 totalBudget。

請注意，如果這個優先順序高於其他限制優先順序，且 totalBudget 極緊，則產生的時間表可能會同時違反員工限製或涵蓋範圍要求。

ShiftAssignment

一名員工擔任輪值指派作業的員工。

JSON 表示法 
{
  "employeeId": string,
  "shiftId": string,
  "roleId": string,
  "breaks": [
    {
      object (Break)
    }
  ]
}
欄位
employeeId

string

指派的員工 ID。
shiftId

string

指派給員工的 Shift ID。
roleId

string

員工指派給值班的角色 ID。
breaks[]

object (Break)

這份輪班作業的休息時間清單。

休息一下

員工在輪班期間中斷工作的時間範圍。

JSON 表示法 
{
  "startDateTime": {
    object (DateTime)
  },
  "durationMinutes": integer
}
欄位
startDateTime

object (DateTime)

休息時間的開始時間。
durationMinutes

integer

廣告插播的時間長度 (以分鐘為單位)。

SolutionStatus

解題工具回應中提供的解決方案 (例如時間表) 狀態。

列舉
SOLUTION_STATUS_UNSPECIFIED 未指定的回應狀態。
FEASIBLE 傳回的時間表雖然可行，但可能不是最佳設定。
OPTIMAL 傳回的時間表為最佳狀態。
INFEASIBLE 指定的限制沒有可行的排程。如果無法滿足優先等級為 PRIORITY_MANDATORY 的任何限制子集，解題工具可能會傳回這個值。
NOT_SOLVED 找不到時間表。
NOT_SOLVED_DEADLINE_EXCEEDED 在指定的時間限制內找不到任何排程。