使用 API 來編輯工作時數行事曆
組織經常需要以程式設計方式建立、編輯或刪除其資源行事曆上的工作時數。 行事曆會顯示可在安排工作排程時決定資源可用性的工作時數、休假和休息時間。 這些資源必須依特定時區進行排程、是否遵守公休日不確定，並且可能會有可變產能。 如需有關在 Field Service 應用程式中定義工作時數的詳細資訊，請移至將工作時數新增至可預約資源。
除了使用 Field Service 應用程式之外，您還可以使用下列 API 來修改所選記錄類型的行事曆規則：
- [儲存行事曆] API (
msdyn_SaveCalendar) 會根據傳遞做為要求的輸入，建立或更新所選實體的行事曆記錄。 - [刪除行事曆] API (
msdyn_DeleteCalendar) 會根據傳遞做為要求的輸入，刪除所選實體的的所有內部行事曆規則。 - 儲存/刪除行事曆 API V2 (msdyn_SaveCalendar/msdyn_DeleteCalendar，傳遞旗標 UseV2) 允許藉由變更重疊規則的邏輯，同時安排多個工作時間定期事項。 如需詳細資訊，請參閱 如果有重疊規則，會發生什麼情況？
本文包含有關每個 API 的輸入 (要求) 和輸出 (回應) 以及其使用方式的詳細資訊，並且還有提供範例。
先決條件
- 隨附通用資源排程 3.12.45.7 版的平台版本 9.2.21055 或更新版本。
- 使用下列其中一個記錄類型：
- 可預約資源 (bookableresource)
- 資源需求 (msdyn_resourcerequirement)
- 工作時數範本 (msdyn_workhourtemplate)
- 專案 (msdyn_project)
行事曆事件類型
建立行事曆時，您可定義工作時間類型出現的次數 (一次、全天、每週或每天，或者您可以建立自訂週期)。 如需這些行事曆事件的詳細資訊，請移至本文章稍後的範例。
發生事項
當工作時間類型在實體行事曆只出現一次時，稱為發生事項。
例如，假設資源從 2021 年 5 月 26 日上午 5:00 工作到上午 10:00。 這些 API 僅支援在同一天內開始和結束的這類型的發生事項。 另舉一例，假設資源從 2021 年 5 月 26 日下午 8:00 工作到 2021 年 5 月 27 日上午 10:00。 您無法僅用一次 msdyn_SaveCalendar API 呼叫建立此發生事項；您必須進行兩次呼叫才行。
全天發生事項
當工作時間類型出現一整天或多個整天 (從開始日期的午夜 (上午 12:00) 起算) 時，這就是全天發生事項。 全天發生事項的最長期間為五年。
例如，資源從 2021 年 5 月 26 日全天工作到 2021 年 5 月 30 日當天結束。 這是持續五天的全天發生事項。
每週定期事項
當工作時間類型出現在每週所選星期幾的相同時間時，這就稱為每週定期事項。
例如，資源在每個星期一、星期二和星期三，從上午 5:00 工作到上午 10:00。
每日定期事項
當工作時間類型出現在每天的相同時間時，這就稱為每日定期事項。
例如，資源在當週的每天，從上午 5:00 工作到上午 10:00。
自訂定期事項
當工作時間類型出現在當週特定幾天的某些時間，但時間在不同天中各異時，您可以建立自訂定期事項。
例如，資源在每星期一上午從 5:00 工作到上午 10:00，並在每星期三從下午 12:00 工作到下午 3:00。
工作時間類型
這些 API 支援下列工作時間類型的建立、更新和刪除作業：
上班時間
上班時間是實體可投入以執行工作的時間。
您可以使用這些 AP 來執行下列作業：
- 建立、編輯或刪除上班時間發生事項。
- 建立、編輯或刪除上班時間每日定期事項。
- 建立、編輯或刪除上班時間每週定期事項。
- 建立、編輯或刪除上班時間自訂定期事項。
- 建立、編輯或刪除全天上班時間。
- 建立或編輯上班時間的產能。
- 編輯定期事項中的單一上班時間發生事項。
- 編輯定期事項中的這個和後續發生事項。
- 將上班時間發生事項變更為定期事項。
- 變更行事曆規則的時區。
您無法使用此 AP 來執行下列作業：
- 刪除定期事項中的單一上班時間發生事項。
- 建立持續 24 小時但不在午夜 (上午 12:00) 開始和結束的發生事項。
- 建立、編輯或刪除全天定期事項。
非上班時間
這些時間是由於未指明的原因，實體無法投入工作的時間。
您可以使用這些 AP 來執行下列作業：
- 建立或編輯全天非上班時間。
- 建立或編輯非上班時間發生事項。
- 變更行事曆規則的時區。
您無法使用這些 AP 來執行下列作業：
- 建立或編輯非上班時間定期事項。
休息時間
這些工作日中的時間，實體要在這段時間中休息，無法投入工作。 沒有上班時間，休息時間就不可能存在；這些休息時間必須出現在一天中的兩段上班時間之間。 休息時間不能與上班時間重疊。
您可以使用這些 AP 來執行下列作業：
- 建立或編輯上班時間中的休息時間。
您無法使用這些 AP 來執行下列作業：
- 僅刪除上班時間發生事項或定期事項中的休息時間。
休假
這些時間是由於假期，實體無法投入工作的時間。 可以指定休假的原因。
您可以使用這些 AP 來執行下列作業：
- 使用標籤建立或編輯休假時間。
- 變更行事曆規則的時區。
您無法使用這些 AP 來執行下列作業：
- 建立或編輯休假時間定期事項。
公休日
您可以建立公休日實體 (定義不營業的時間)。 您可以透過 msdyn_SaveCalendar API，使用選擇性 ObserveClosure 金鑰來設定，讓每個實體遵守或忽略組織的公休日時間。 將其設定為遵守這些公休日時，無法將這些實體用於工作。
儲存行事曆 API
輸入
此要求僅包含一個字串類型的屬性：CalendarEventInfo。 此屬性包含數個其他屬性，全都內嵌在此字串中。
注意
在下表中，類型表示預期會要求成功的格式。 不過，整個要求會解析為單一字串。
CalendarEventInfo
| 名字 | 輸入 | 必要項目 | 描述 |
|---|---|---|---|
| EntityLogicalName | String | .是 | 此金鑰描述進行 API 呼叫的實體。 將要建立或編輯此實體的行事曆。 |
| CalendarId | GUID | .是 | 此金鑰包含與上述實體相關的行事曆識別碼。 建立這其中任何一個實體時，也會自動建立行事曆記錄。 這些 API 藉由新增規則或編輯現有規則來編輯該行事曆記錄。 |
| RulesAndRecurrences | RulesAndRecurrences | .是 | 此金鑰是陣列，每個元素都包含下一節表格中列出的多個屬性。 陣列的大小應至少為一個。 |
| IsVaried | Boolean | 無 | 在自訂定期事項案例中，應將此金鑰應設定為 true。 |
| IsEdit | Boolean | 無 | 在編輯現有規則時，應將此金鑰應設定為 true。 |
| TimeZoneCode | Integer | 無 | 此金鑰接受與行事曆規則時區對應的整數值。 如需了解對應，請移至本文稍後的時區代碼 。 預設值是使用者的時區。 |
| InnerCalendarDescription | String | 無 | 只有在行事曆規則是對休假使用時，才需要此金鑰。 其中必須包含休假的原因。 |
| ObserveClosure | Boolean | 無 | 這是定期事項專用的金鑰。 如果設定為 true，則實體遵守公休日的作息。 |
| RecurrenceEndDate | 日期時間 | 無 | 這是定期事項專用的金鑰。 其中包含定期事項的結束日期。 如果時間戳記為 08:00:00 或更早，則定期事項結束日期為指定日期的前一天。 如果時間戳記為 08:00:01 或更晚，則遵循該日期原本的作息。 定期事項的預設值為 Null。 定期事項的預設值為 9999 年 12 月 30 日 23:59:59 UTC 時間。 |
| RecurrenceSplit | Boolean | 無 | 這是定期事項專用的金鑰。 在編輯定期事項的「這個和後續發生事項」時，這會設定為 true。 |
| ResourceId | GUID | 無 | 此金鑰包含 SystemUserId 或 ResourceId，並且只有在與此呼叫相關的實體是類型為 SystemUser 的可預約資源時才要傳遞。 這是檢查服務管理索引標籤上的 OwnCalendar 權限時所需的金鑰。 |
| UseV2 | 旗標 | 無 | 傳遞此旗標會啟用 V2 版本的工作時數行事曆，並提供允許多個定期事項的增強型重疊規則邏輯。 如需詳細資訊，請參閱 如果有重疊規則，會發生什麼情況？ |
RulesAndRecurrences
| 名稱 | 類型 | 必要 | 描述: |
|---|---|---|---|
| 規則 | 規則 | .是 | 此金鑰是陣列，每個元素都包含下一節表格中列出的多個屬性。 陣列的大小應至少為一個。 |
| RecurrencePattern | String | 無 | 這是定期事項專用的金鑰。 目前僅支援此模式：FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA。 BYDAY 可以變更為包含更少的天數；不過，無法變更 FREQ 和 INTERVAL。 |
| InnerCalendarId | GUID | 無 | 這是編輯專用的金鑰。 如果要編輯規則，則必須在此處傳遞 InnerCalendarId。 如果沒有傳遞 InnerCalendarId，API 就會建立新規則，即使 IsEdit 金鑰已設定為 True。 |
| 動作 | Integer | 無 | 這是自訂定期事項專用的金鑰。 如果要建立或編輯自訂定期事項，則必須輸入下列其中一個數字：
|
規則
| 名字 | 類型 | 必填 | 描述 |
|---|---|---|---|
| StartTime | DateTime | .是 | 此金鑰包含 ISO 格式的日期時間輸入。 例如：\"2021-05-15T12:00:00.000Z\"。 時間部分決定先前所指定時區的工作時間開始時間。 日期部分決定工作時間的開始日期。 這裡的 2021 年 5 月 15 日是發生事項日期或定期事項開始日期。 如果模式為 BYDAY=TU,WE，但 5 月 15 日 (星期六) 為日期，則 API 會自動建立或編輯 5 月 15 日之後所有星期二和星期三的規則。 這正是規則不一定有與日期相對應之當週天次的情況。 |
| EndTime | DateTime | .是 | 這會包含 ISO 格式的日期時間輸入。 例如：\"2021-05-15T12:00:00.000Z\"。 時間部分決定先前所指定時區的工作時間結束時間。 日期部份必須包含與 StartTime 之日期部分相同的日期。 唯一的例外是：
|
| WorkHourType | Integer | .是 | 此金鑰包含與下列其中一個選項相對應的數字：
|
| 投入 | Integer | 無 | 此金鑰決定實體的產能。 這必須是整數。 預設值是 1。 |
輸出
此 POST API 會建立或修改所選實體的行事曆規則記錄。 這還會產生下列輸出。
| 名稱 | 類型 | 描述 |
|---|---|---|
| InnerCalendarIds | String | InnerCalendarIds GUID 陣列，其中元素是 POST 作業的結果。. |
刪除行事曆 API
輸入
| 名字 | 輸入 | 必要項目 | 描述 |
|---|---|---|---|
| EntityLogicalName | String | .是 | 此欄位描述要刪除其行事曆規則的實體。 |
| InnerCalendarId | GUID | .是 | 此欄位描述必須刪除之 InnerCalendarId 的識別碼。 如果有多個與單一規則相關聯的 InnerCalendarIds，則任何一個識別碼在這裡都充分適用。 其他有關內部和外部行事曆的資訊：行事曆實體 |
| CalendarId | GUID | .是 | 此欄位描述實體的 CalendarId。 |
| IsVaried | Boolean | 無 | 這是定期事項專用的欄位，如果要刪除自訂定期事項規則，則設定為 yes。 |
| UseV2 | 旗標 | 無 | 傳遞此旗標會啟用 V2 版本的工作時數行事曆，並提供允許多個定期事項的增強型重疊規則邏輯。 如需詳細資訊，請參閱 如果有重疊規則，會發生什麼情況？ |
輸出
此 POST API 會刪除所選實體的行事曆規則記錄。 此外，還會產生下列輸出。
| 名稱 | 類型 | 描述 |
|---|---|---|
| InnerCalendarIds | String | InnerCalendarIds GUID 陣列，其中元素是 POST 作業的結果。. |
載入行事曆 API
輸入
名稱：msdyn_LoadCalendars
類型：動作
描述：傳回指定 LoadCalendarsInput 的行事曆。
名稱：msdyn_LoadCalendars.LoadCalendarsInput
類型：參數
描述：JSON 格式的字串：
{
StartDate: string,
EndDate: string,
CalendarIds: string[]
}
名稱：msdyn_LoadCalendarsResponse
類型：ComplexType
描述：包含 msdyn_loadCalendars 動作的回應。
名稱：msdyn_LoadCalendarsResponse.CalendarEvents
類型：屬性
描述：JSON 格式的字串：
{
"calendarId": CalendarEventSlot[]
}
其中 calendarId 是代表行事曆 GUID 的正確 guid，而 CalendarEventSlot 是以下格式的物件：
{
CalendarId: string,
InnerCalendarId: string,
Start: string,
End: string,
Effort: double
}
如何呼叫 API
可以使用瀏覽器來呼叫這些 API。
- 開啟您需要進行這些行事曆變更所在的瀏覽器和組織。
- 開啟開發人員工具 (在 Microsoft Edge 中選取 Ctrl+Shift+I，在 Google Chrome 中選取 F12)。
- 在主控台中，以組織詳細資料 (例如
http://your_org.crm.dynamics.com) 取代 [組織名稱] 之後，輸入下列函數：
function CalendarAction(action, data) {
let req = new XMLHttpRequest();
req.open("POST", "**[org-name]**/api/data/v9.0/" + action, true);
req.setRequestHeader("OData-MaxVersion", "4.0");
req.setRequestHeader("OData-Version", "4.0");
req.setRequestHeader("Accept", "application/json");
req.setRequestHeader("Content-Type", "application/json; charset=utf-8");
req.setRequestHeader("Prefer", 'odata.include-annotations="*"');
req.onreadystatechange = function () {
if (this.readyState === 4) {
req.onreadystatechange = null;
if(this.status == 200) {
console.log(JSON.parse(this.response));
} else {
console.error(JSON.parse(this.response));
}
}
};
req.send(JSON.stringify(data));
}
- 定義此函數後，您可以使用 API 呼叫該函數來建立、編輯或刪除行事曆。 輸入下列呼叫以儲存行事曆：
CalendarAction("msdyn_SaveCalendar",{
"CalendarEventInfo":"{
\"CalendarId\":\"df0857c4-50f5-4576-8e89-f236670ad2d5\",
\"EntityLogicalName\":\"bookableresource\",
\"TimeZoneCode\":92,\"StartDate\":\"2021-04-25T00:00:00.000Z\",
\"IsVaried\":false,
\"RulesAndRecurrences\":[{
\"Rules\":[{
\"StartTime\":\"2021-04-25T08:00:00.000Z\",
\"EndTime\":\"2021-04-25T17:00:00.000Z\",
\"Duration\":540,
\"Effort\":1
}]
}]
}"
})
輸入下列呼叫以刪除行事曆：
CalendarAction("msdyn_DeleteCalendar", {
"CalendarEventInfo":"{
\"CalendarId\":\"8390358c-77d0-430f-b176-f27adadac8eb\",
\"EntityLogicalName\":\"bookableresource\",
\"InnerCalendarId\":\"cf508c2c-5c55-485c-be1e-d2ebcb385441\"
}"
})
請參閱下節有關如何根據需求進行不同呼叫的範例。 將步驟 3 中函數呼叫的 action 取代為 msdyn_SaveCalendar 或 msdyn_DeleteCalendar，並將 data 取代為相關的 CalendarEventInfo。
另請參閱下列螢幕擷取畫面，以了解 Power Automate 對 msdyn_SaveCalendar 動作的呼叫：
API 使用方式的範例案例
我們來逐步解說一些可以使用這些 API 的案例。
Bob 和 Tim 是 Contoso Enterprises 在華盛頓州貝爾維尤市的送貨卡車司機。 他們的調度員 Debbie 負責變更工作時間行事曆。 Debbie 使用 msdyn_SaveCalendar API 和 msdyn_DeleteCalendar API 來進行這些變更。
建立上班時間發生事項。
Bob 經排定要從 2021 年 5 月 15 日上午 9:00 到下午 5:00 開車四處遞送包裹。 Debbie 使用 msdyn_SaveCalendar API。
要求
{
"CalendarEventInfo": "{\"CalendarId\":\"d33263c7-c16b-4e3e-a56a-20f7a66cafc1\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-15T09:00:00.000Z\",\"EndTime\":\"2021-05-15T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}]}]}"
}
回應
{
"InnerCalendarIds": "[\"f76cc333-cbbe-eb11-a81d-000d3a6e4359\"]"
}
編輯上班時間發生事項。
Bob 的排程隨後變更成從 2021 年 5 月 15 日上午 10:00 開始工作。 Debbie 使用 msdyn_SaveCalendar API。
要求
{
"CalendarEventInfo": "{\"CalendarId\":\"d33263c7-c16b-4e3e-a56a-20f7a66cafc1\",\"EntityLogicalName\":\"bookableresource\",\"IsEdit\":\"true\",\"TimeZoneCode\":5,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-15T10:00:00.000Z\",\"EndTime\":\"2021-05-15T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}], \"InnerCalendarId\":\"f76cc333-cbbe-eb11-a81d-000d3a6e4359\"}]}"
}
回應
{
"InnerCalendarIds": "[\"f76cc333-cbbe-eb11-a81d-000d3a6e4359\"]"
}
刪除上班時間發生事項。
家中突發緊急情況，Bob 必須取消其一整天的工作。 Debbie 使用 msdyn_DeleteCalendar API。
Request
{
"CalendarEventInfo": "{\"CalendarId\":\"d33263c7-c16b-4e3e-a56a-20f7a66cafc1\",\"EntityLogicalName\":\"bookableresource\",\"InnerCalendarId\":\"f76cc333-cbbe-eb11-a81d-000d3a6e4359\"}"
}
回覆
{
"InnerCalendarIds": "[\"f76cc333-cbbe-eb11-a81d-000d3a6e4359\"]"
}
建立上班時間每日定期事項
從 2021 年 5 月 20 日起，Bob 決定整週從 8:00 AM 到 5:00 PM 在 Contoso 工作，並將於 2021 年 7 月 15 日停止工作。
Request
{
"CalendarEventInfo": "{\"CalendarId\":\"d33263c7-c16b-4e3e-a56a-20f7a66cafc1\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"RecurrenceEndDate\":\"2021-07-15T00:00:00.000Z\",\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-20T08:00:00.000Z\",\"EndTime\":\"2021-05-20T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA\"}]}"
}
回覆
{
"InnerCalendarIds": "[\"20f6cfa7-cfbe-eb11-a81d-000d3a6e4359\"]"
}
以增加的產能編輯上班時間每日定期事項
因為需要休息，Bob 決定從 2021 年 6 月 15 日起停止整週的工作。 在那之前，Bob 會繼續執行他先前同意的整週排程。 Debbie 使用 msdyn_SaveCalendar API 來進行這些變更。
要求
{
"CalendarEventInfo": "{\"CalendarId\":\"d33263c7-c16b-4e3e-a56a-20f7a66cafc1\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"RecurrenceEndDate\":\"2021-06-15T00:00:00.000Z\",\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-20T08:00:00.000Z\",\"EndTime\":\"2021-05-20T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"InnerCalendarId\":\"20f6cfa7-cfbe-eb11-a81d-000d3a6e4359\",\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA\"}]}"
}
回應
{
"InnerCalendarIds": "[\"867a2461-cdbe-eb11-a81d-000d3a6e4359\"]"
}
建立上班時間每週定期事項
從 2021 年 6 月 16 日開始，Bob 將在星期三和星期五的 8:00 AM 到 5:00 PM 工作，並在 12:00 PM 到 12:30 PM 吃午餐。 Debbie 使用 msdyn_SaveCalendar API，但她犯了錯誤，將休息時間排安排成 12:00 PM 到 1:00 PM。
Request
{
"CalendarEventInfo": "{\"CalendarId\":\"d33263c7-c16b-4e3e-a56a-20f7a66cafc1\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-06-16T08:00:00.000Z\",\"EndTime\":\"2021-06-16T12:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}, {\"StartTime\":\"2021-06-16T12:00:00.000Z\",\"EndTime\":\"2021-06-16T13:00:00.000Z\",\"Effort\":null,\"WorkHourType\":1}, {\"StartTime\":\"2021-06-16T13:00:00.000Z\",\"EndTime\":\"2021-06-16T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=WE,TH,FR\"}]}"
}
回覆
{
"InnerCalendarIds": "[\"1f894441-d0be-eb11-a81d-000d3a6e4359\"]"
}
編輯上班時間每週定期事項中的休息時間
Debbie 隨後更正她的錯誤，使用 msdyn_SaveCalendar API 將休息時間變更為 12:00 PM 到 12:30 PM。
要求
{
"CalendarEventInfo": "{\"CalendarId\":\"d33263c7-c16b-4e3e-a56a-20f7a66cafc1\",\"EntityLogicalName\":\"bookableresource\",\"IsEdit\":\"true\",\"TimeZoneCode\":5,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-06-15T08:00:00.000Z\",\"EndTime\":\"2021-06-15T12:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}, {\"StartTime\":\"2021-06-15T12:00:00.000Z\",\"EndTime\":\"2021-06-15T12:30:00.000Z\",\"Effort\":null,\"WorkHourType\":1}, {\"StartTime\":\"2021-06-15T12:30:00.000Z\",\"EndTime\":\"2021-06-15T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"InnerCalendarId\":\"1f894441-d0be-eb11-a81d-000d3a6e4359\",\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=WE,TH,FR\"}]}"
}
回應
{
"InnerCalendarIds": "[\"1f894441-d0be-eb11-a81d-000d3a6e4359\"]"
}
建立上班時間自訂定期事項
Tim 在星期一為 Contoso 從上午 8:00 工作到下午 5:00，而在星期三從上午 11:00 工作到下午 3:00。 Tim 從 2021 年 5 月 16 日開始在 Contoso 工作 Debbie 使用 msdyn_SaveCalendar API 來建立 Tim 的工作時間。
要求
{
"CalendarEventInfo": "{\"CalendarId\":\"a68245c9-ba2e-4496-9c18-3bee75fda396\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"IsVaried\":true,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-16T08:00:00.000Z\",\"EndTime\":\"2021-05-16T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"Action\":1,\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO\"},{\"Rules\":[{\"StartTime\":\"2021-05-16T11:00:00.000Z\",\"EndTime\":\"2021-05-16T15:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"Action\":1,\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=WE\"}]}"
}
回應
{
"InnerCalendarIds": "[\"9fb8c199-d1be-eb11-a81d-000d3a6e4359\", \"a2b8c199-d1be-eb11-a81d-000d3a6e4359\"]"
}
編輯上班時間自訂定期事項
Tim 的排程隨後變更：他的工作時間變更為星期三 5:00 PM 到 8:00 PM，以及星期四 10:00 AM 到 12:00 PM。 星期一已從 Tim 的排程移除。 Debbie 使用 msdyn_SaveCalendar API 來完成這項變更。
Request
{
"CalendarEventInfo": "{\"CalendarId\":\"a68245c9-ba2e-4496-9c18-3bee75fda396\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"IsVaried\":true,\"IsEdit\":true,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-16T08:00:00.000Z\",\"EndTime\":\"2021-05-16T17:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"Action\":2,\"InnerCalendarId\":\"9fb8c199-d1be-eb11-a81d-000d3a6e4359\",\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=MO\"},{\"Rules\":[{\"StartTime\":\"2021-05-16T17:00:00.000Z\",\"EndTime\":\"2021-05-16T20:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"Action\":3,\"InnerCalendarId\":\"a2b8c199-d1be-eb11-a81d-000d3a6e4359\",\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=WE\"}, {\"Rules\":[{\"StartTime\":\"2021-05-16T10:00:00.000Z\",\"EndTime\":\"2021-05-16T12:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}],\"Action\":1,\"InnerCalendarId\":null,\"RecurrencePattern\":\"FREQ=WEEKLY;INTERVAL=1;BYDAY=TH\"}]}"
}
回覆
{
"InnerCalendarIds": "[\"a2b8c199-d1be-eb11-a81d-000d3a6e4359\", \"942bda0f-d3be-eb11-a81d-000d3a6e4359\"]"
}
編輯定期事項中的上班時間發生事項
在 2021 年 5 月 26 日，Tim 只能從下午 1:00 工作到下午 7:00。 Debbie 在這裡使用 msdyn_SaveCalendar API。
Request
{
"CalendarEventInfo": "{\"CalendarId\":\"a68245c9-ba2e-4496-9c18-3bee75fda396\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-26T13:00:00.000Z\",\"EndTime\":\"2021-05-26T19:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}], \"InnerCalendarId\":\"a2b8c199-d1be-eb11-a81d-000d3a6e4359\"}]}"
}
回覆
{
"InnerCalendarIds": "[\"a2b8c199-d1be-eb11-a81d-000d3a6e4359\"]"
}
刪除上班時間自訂定期事項
Tim 因為已決定離開公司，且必須刪除他的整個排程。 Debbie 在這裡使用 msdyn_DeleteCalendar API。
Request
{
"CalendarEventInfo": "{\"CalendarId\":\"a68245c9-ba2e-4496-9c18-3bee75fda396\",\"EntityLogicalName\":\"bookableresource\",\"InnerCalendarId\":\"34d2210c-9fb6-eb11-a820-000d3afb1dba\",\"IsVaried\":true}"
}
回覆
{
"InnerCalendarIds": "[\"a2b8c199-d1be-eb11-a81d-000d3a6e4359\", \"942bda0f-d3be-eb11-a81d-000d3a6e4359\"]"
}
建立休假
從 2021 年 6 月 9 日開始，Tim 將休假三天享受家庭度假。
要求
{
"CalendarEventInfo": "{\"CalendarId\":\"a68245c9-ba2e-4496-9c18-3bee75fda396\",\"InnerCalendarDescription\":\"Family Vacation\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-06-15T00:00:00.000Z\",\"EndTime\":\"2021-06-17T00:00:00.000Z\",\"Effort\":1,\"WorkHourType\":3}]}]}"
}
回應
{
"InnerCalendarIds": "[\"266c434e-d5be-eb11-a81d-000d3a6e4359\"]"
}
建立全天上班時間
Tim 從 2021 年 5 月 20 日開始 72 小時的輪班。 Debbie 使用 msdyn_SaveCalendar API 來建立 Tim 的工作時間。
Request
{
"CalendarEventInfo": "{\"CalendarId\":\"a68245c9-ba2e-4496-9c18-3bee75fda396\",\"EntityLogicalName\":\"bookableresource\",\"TimeZoneCode\":5,\"RulesAndRecurrences\":[{\"Rules\":[{\"StartTime\":\"2021-05-20T00:00:00.000Z\",\"EndTime\":\"2021-05-22T00:00:00.000Z\",\"Effort\":1,\"WorkHourType\":0}]}]}"
}
回覆
{
"InnerCalendarIds": "[\"6e160a8e-d5be-eb11-a81d-000d3a6e4359\"]"
}
常見問題集
收到錯誤「StartTime 不可大於或等於 EndTime。」
確認不同行事曆規則的時段中沒有重疊。 檢查日期以確定 StartTime 不晚於 EndTime。 此外，還要確認時間遵循 24 小時格式。
是否可以使用 API 來更新「工作時數範本」實體？
是的，您可以使用此 API 來建立和更新工作時數範本，以及資源工作時數。
收到錯誤「還原序列化 Microsoft.Dynamics.UCICalendar.Plugins.SaveCalendarContract+CalendarEventInfo 類型的物件時發生錯誤。 輸入來源的格式不正確。
或
必須為狀態 'Element'.. 發現名稱為 '', namespace '' 的 'Text'。」
確認字串解析正確。 可能會有括號、逗號或分號遺失。
收到錯誤「定期模式無效。 請參閱支援的模式文件。」
目前僅支援此模式：FREQ=DAILY;INTERVAL=1;BYDAY=SU,MO,TU,WE,TH,FR,SA。 BYDAY 可以變更為包含更少的天數；不過，無法變更 FREQ 和 INTERVAL。 確認模式中沒有空格。
如何取得資源的 CalendarId 和 InnerCalendarId 的資訊？
您可以從資源屬性擷取 CalendarId。 進行以下呼叫來取得此資訊：[org-url]/api/data/v9.1/bookableresources([bookableresourceGUID])。
例如，先前的呼叫會是 [org-url]/api/data/v9.1/bookableresources(7bb0224b-6712-ec11-94f9-000d3a6d888e)。
您可以從行事曆屬性擷取 InnerCalendarId。 進行以下呼叫來取得此資訊：[org-url]/api/data/v9.1/calendars([calendar-id-from-above-call])?$expand=calendar_calendar_rules。
例如，先前的呼叫會是 [org-url]/api/data/v9.1/calendars(02481736-1b6a-4d49-9ebd-a5bd041c1c99)?$expand=calendar_calendar_rules。
如果有重疊的規則，會發生什麼情況？
規則會歸入幾個不同的順位：
- 順位 1 - 每天項目 (上班/非上班) 和休假項目。
- 順位 0 - 每週項目 (上班/非上班)。
V2 重疊規則
- 順位 1 規則的優先順序高於順位 0 規則。 如果同一天有兩個規則 (每個順位各一個)，則每日項目或休假項目會比每週項目優先處理。
- 當相同日期範圍內有多個順位 0 規則時：
- 如果時間不相交，兩者都會保留在行事曆上。
- 如果時間相交，則最近建立/修改的規則會是資源行事曆納入考量的規則。 所有其他在日期範圍內有交集的規則都會遭到移除。 如果一些順位為 0 的規則在某些日期有交集，但在其他日期沒有交集，則會接合規則以保留無相交部分，同時刪除相交部分。
V2 行事曆行為範例：
範例 1 - 重複工作時數：沒有重疊日/時間的重疊日期
對於指定的日期範圍，技術人員在不同的日子裡上早班、午班或夜班。
為指定的日期範圍建立第一個重複行事曆規則。 例如：重複週一、週二；1.1-4.1；東部時間上午 8 點 - 下午 5 點。
為相交的日期範圍建立第二個重複行事曆規則，同時確定工作時數未與先前的日期或時間相交。 例如：重複週三、週四；1.1-4.1；東部時間上午 8 點 - 下午 5 點或重複週一、週二；1.1-4.1；東部時間下午 8 點。
結果：這兩個行事曆規則都會保留且並存。
範例 2 - 重複工作時數：存在重疊日期，其中第二個規則的開始日期/結束日期出現在第一個規則的日期之前或之後，包括所有重疊日
技術人員會獲得新的工作排程，取代其舊排程中的幾週。 依據合約，他們每週都在同幾天工作。
為指定的日期範圍建立第一個重複行事曆規則。 例如：重複週一、週二；2.1-4.1；東部時間上午 8 點 - 下午 5 點。
為重疊的日期範圍建立第二個重複行事曆規則，其中所有工作日都有重疊的工作時數。 為此新規則選擇在第一條規則開始/結束日期之前或之後的開始/結束日期。 例如：重複週一、週二；3.1-5.1；東部時間下午 1 點 - 下午 8 點。
結果：截斷第一個規則，以適應第二個規則的開始/結束日期。 例如：重複週一、週二；2.1-2.28；東部時間上午 8 點 - 下午 5 點和重複週一、週二；3.1-5.1；東部時間下午 1 點 - 下午 8 點。
範例 3 - 重複工作時數：所有包含一些重疊日/時間的重疊日期
技術人員是固定 2 個月期間的合約工作者。 他們已同意在某些日子裡承擔額外的工作。 他們希望將星期二的工作時數轉移至更早/更晚的時間。
為指定的日期範圍建立一些重複行事曆規則。 例如：重複週一、週二；2.1-4.1；東部時間上午 8 點 - 下午 12 點和重複週二、週三；2.1-4.1；東部時間下午 1 點 - 下午 5 點。
為相同的日期範圍建立新的重複行事曆規則。 選擇與原始規則部分重疊的日/時間。 例如：重複週二，週四；2.1-4.1；東部時間上午 10 點 - 下午 2 點。
結果：新規則覆寫有重疊的舊位置，並讓其他位置保持不變。 例如：重複週一；2.1-4.1；東部時間上午 8 點 - 下午 12 點和重複週三；2.1-4.1；東部時間下午 1 點 - 下午 5 點和重複週二、週四；2.1-4.1；東部時間上午 10 點 - 下午 2 點
範例 4 - 重複工作時數：舊規則中包含的新規則，一些重疊日/時間
技術人員每星期在週一至週五上午 8 點-下午 5 點工作。 就在這兩週裡，他們會在每週一至週三處理特殊的緊急專案，工作時間從上午 6 點到下午 6 點不等。
為指定的日期範圍建立第一個重複行事曆規則。 例如：重複週一、週二、週三、週四；1.1 - 無結束日期；東部時間上午 8 點 - 下午 5 點
建立包含在上述日期範圍中的第二個重複行事曆規則，請選擇在某些天重疊的工作時數。 例如：重複週一、週二、週三；5.1-5.14；東部時間上午 6 點 - 下午 6 點。
結果：本練習結束時，行事曆應應該會有四個重複規則：
- 將第一個規則截斷至第二個規則的開始日期
- 第二個行事曆規則
- 建立與第一個規則類似的新規則，但使用第二個規則的日期做為非重疊的日期
- 截斷第一個規則，使其從第二個規則的結束日期開始，但沒有結束日期
例如：重複週一、週二、週三、週四、週五；1.1–4.30；東部時間上午 8 點 - 下午 5 點和重複週一、週二、週三；5.1-5.14；東部時間上午 6 點 - 下午 6 點和重複週四、週五；5.1-5.14；東部時間上午 8 點 - 下午 5 點和重複週一、週二、週三、週四、週五；5.15 – 無結束日期；東部時間上午 8 點 - 下午 5 點
範例 5 - 非重複工作時數 (發生事項，順位 1 規則)
技術人員有多個團隊凝聚日，這些日期優先於當天所有其他工作時間實例。
為指定的日期範圍建立重複行事曆規則。 例如：重複週一、週二、週三、週四；1.1 - 無結束日期；東部時間上午 8 點 - 下午 5 點
建立包含在上述日期範圍內的非重複行事曆規則。 選擇某些天重疊的工作時數。 例如：不重複；6.21；東部時間上午 7 點 - 下午 1 點。
結果：練習結束時，行事曆應該會有 1 個非重複規則 (發生事項)。 非重複規則覆寫一整天的重疊重複事件。 例如：重複週一、週二、週三、週四、週四、週五；1.1 - 無結束日期但6.21；非重複；東部時間上午 7 點 - 下午 1 點除外。
V1 重疊規則
- 順位 1 規則的優先順序高於順位 0 規則。 因此，如果同一天有兩個規則 (每個順位各一個)，則每日項目或休假項目會比每週項目優先處理。
- 如果有兩個相同順位的規則，則最近建立/修改的規則會是資源行事曆納入考量的規則。
- 請記住，全天項目屬於順位 1，因此您可能需要將其變更為每週項目，才能新增上班時間項目，並使這些項目不受影響。
- 如果有上班時間，且建立了與此時間重疊的休假項目時，規則會以確保不影響休假的方式來分割，而任何做為上班時間的剩餘時間為上班時間將保持原樣。 例如，如果 9 月 21 日有從上午 8 點至下午 5 點的上班時間，並在 9 月 21 日新增從下午 3 點到下午 7 點的休假項目時，這就會解析為下午 8 點到下午 3 點的上班時間以及下午 3 點到下午 7 點的休假。 不過，如果規則是以相反的順序建立 (先建立休假，然後建立上班時間)，而不考慮時段，則只會重新選取上班時間。 將會覆寫休假。
時區代碼
| 列舉 | 時區 |
|---|---|
| 12 | (GMT-12:00) 國際換日線西 |
| 1 | (GMT+13:00) 薩摩亞 |
| 2 | (GMT-10:00) 夏威夷 |
| 3 | (GMT-09:00) 阿拉斯加 |
| 4 | (GMT-08:00) 太平洋時間 (美國及加拿大) |
| 5 | (GMT-08:00) 下加利福尼亞 |
| 6 | (GMT-11:00) 國際標準時間-11 |
| 7 | (GMT-10:00) 阿留申群島 |
| 8 | (GMT-09:30) 馬克沙斯群島 |
| 9 | (GMT-09:00) 國際標準時間-09 |
| 10 | (GMT-07:00) 山區時間 (美國和加拿大) |
| 11 | (GMT-08:00) 國際標準時間-08 |
| 12 | (GMT-07:00) 奇瓦瓦、拉巴斯、馬薩特蘭 |
| 15 | (GMT-07:00) 亞利桑那 |
| 20 | (GMT-06:00) 中部時間 (美國和加拿大) |
| 25 | (GMT-06:00) 薩克其萬省 |
| 29 | (GMT-06:00) 瓜達拉哈拉、墨西哥城、蒙特雷 |
| 33 | (GMT-06:00) 中美洲 |
| 34 | (GMT-06:00) 伊斯特島 |
| 35 | (GMT-05:00) 東部時間 (美國和加拿大) |
| 40 | (GMT-05:00) 印地安那州 (東部) |
| 43 | (GMT-05:00) 海地 |
| 44 | (GMT-05:00) 哈瓦那 |
| 45 | (GMT-05:00) 波哥大，利馬，基多，里約布蘭科 |
| 47 | (GMT-04:00) 卡拉卡斯 |
| 50 | (GMT-04:00) 大西洋時間 (加拿大) |
| 51 | (GMT-05:00) 土克斯及開科斯 |
| 55 | (GMT-04:00) 佐治敦，拉帕茲，聖胡安 |
| 56 | (GMT-04:00) 聖地牙哥 |
| 58 | (GMT-04:00) 古雅巴 |
| 59 | (GMT-04:00) 亞松森 |
| 60 | (GMT-03:30) 紐芬蘭 |
| 65 | (GMT-03:00) 巴西利亞 |
| 69 | (GMT-03:00) 布宜諾斯艾利斯 |
| 70 | (GMT-03:00) 卡宴，福塔力沙 |
| 71 | (GMT-03:00) 薩爾瓦多 |
| 72 | (GMT-03:00) 聖匹島 |
| 73 | (GMT-03:00) 格陵蘭 |
| 74 | (GMT-03:00) 蒙特維多 |
| 75 | (GMT-02:00) 大西洋中部 |
| 76 | (GMT-02:00) 國際標準時間-02 |
| 77 | (GMT-03:00) 阿拉瓜伊納 |
| 80 | (GMT-01:00) 亞速爾群島 |
| 83 | (GMT-01:00) 維德角 |
| 84 | (GMT+01:00) 卡薩布蘭卡 |
| 85 | (GMT+00:00) 都柏林，愛丁堡，里斯本，倫敦 |
| 90 | (GMT+00:00) 蒙羅維亞，雷克雅維克 |
| 92 | (GMT) 國際標準時間 |
| 95 | (GMT+01:00) 貝爾格萊德、布拉迪斯拉發、布達佩斯、盧布爾雅那、布拉格 |
| 100 | (GMT+01:00) 塞拉耶佛、斯高彼亞、華沙、札格雷布 |
| 105 | (GMT+01:00) 布魯塞爾、哥本哈根、馬德里、巴黎 |
| 110 | (GMT+01:00) 阿姆斯特丹、柏林、伯恩、羅馬、斯德哥爾摩、維也納 |
| 113 | (GMT+01:00) 中非西部 |
| 115 | (GMT+02:00) 奇西瑙 |
| 120 | (GMT+02:00) 開羅 |
| 125 | (GMT+02:00) 赫爾辛基，凱耶夫，里加，蘇非亞，塔林，維爾紐斯 |
| 129 | (GMT+02:00) 安曼 |
| 130 | (GMT+02:00) 雅典，布加勒斯特 |
| 131 | (GMT+02:00) 貝魯特 |
| 133 | (GMT+02:00) 大馬士革 |
| 134 | (GMT+03:00) 伊斯坦堡 |
| 135 | (GMT+02:00) 耶路撒冷 |
| 140 | (GMT+02:00) 哈拉雷、普勒托利亞 |
| 141 | (GMT+02:00) 溫荷克 |
| 142 | (GMT+02:00) 加薩，希伯侖 |
| 145 | (GMT+03:00) 莫斯科，聖彼得堡 |
| 150 | (GMT+03:00) 科威特、利雅德 |
| 151 | (GMT+03:00) 明斯克 |
| 155 | (GMT+03:00) 奈洛比 |
| 158 | (GMT+03:00) 巴格達 |
| 159 | (GMT+02:00) 卡里寧格勒 |
| 160 | (GMT+03:30) 德黑蘭 |
| 165 | (GMT+04:00) 阿布達比、馬斯喀特 |
| 169 | (GMT+04:00) 巴庫 |
| 170 | (GMT+04:00) 葉里溫 |
| 172 | (GMT+04:00) 路易士港 |
| 173 | (GMT+04:00) 第比利斯 |
| 174 | (GMT+04:00) 伊熱夫斯克，沙馬拉 |
| 175 | (GMT+04:30) 喀布爾 |
| 176 | (GMT+04:00) 阿斯特拉罕，烏里揚諾夫斯克 |
| 180 | (GMT+05:00) 葉卡捷琳堡 |
| 184 | (GMT+05:00) 伊斯蘭馬巴德，喀拉蚩 |
| 185 | (GMT+05:00) 塔什干 |
| 190 | (GMT+05:30) 清奈、加爾各答、孟買，新德里 |
| 193 | (GMT+05:45) 加德滿都 |
| 195 | (GMT+06:00) 阿斯塔那 |
| 196 | (GMT+06:00) 達卡 |
| 197 | (GMT+06:00) 鄂木斯克 |
| 200 | (GMT+05:30) 斯里哈亞華登尼普拉 |
| 201 | (GMT+07:00) 新西伯利亞 |
| 203 | (GMT+06:30) 仰光 (仰光) |
| 205 | (GMT+07:00) 曼谷、河內、雅加達 |
| 207 | (GMT+07:00) 克拉斯諾亞爾斯克 |
| 208 | (GMT+07:00) 巴爾瑙爾，戈爾諾-阿爾泰斯克 |
| 209 | (GMT+07:00) 哈霍德 |
| 210 | (GMT+08:00) 北京，重慶，香港特別行政區，烏魯木齊 |
| 211 | (GMT+07:00) 托木斯克 |
| 215 | (GMT+08:00) 吉隆坡、新加坡 |
| 220 | (GMT+08:00) 台北 |
| 225 | (GMT+08:00) 伯斯 |
| 227 | (GMT+08:00) 伊爾庫次克 |
| 228 | (GMT+08:00) 庫倫 |
| 229 | (GMT+09:00) 平壤 |
| 230 | (GMT+09:00) 首爾 |
| 231 | (GMT+08:45) 尤克拉 |
| 235 | (GMT+09:00) 大阪、札幌、東京 |
| 240 | (GMT+09:00) 雅庫次克 |
| 241 | (GMT+09:00) 赤塔 |
| 245 | (GMT+09:30) 達爾文 |
| 250 | (GMT+09:30) 阿得雷德 |
| 255 | (GMT+10:00) 坎培拉、墨爾本、雪梨 |
| 260 | (GMT+10:00) 布里斯本 |
| 265 | (GMT+10:00) 霍巴特 |
| 270 | (GMT+10:00) 海參威 |
| 274 | (GMT+10:30) 羅豪島 |
| 275 | (GMT+10:00) 關島、摩斯比港 |
| 276 | (GMT+11:00) 布干維爾島 |
| 277 | (GMT+11:00) 諾福克島 |
| 278 | (GMT+11:00) 庫頁島 |
| 279 | (GMT+11:00) 喬庫爾達赫 |
| 280 | (GMT+11:00) 索羅門群島，新喀里多尼亞群島 |
| 281 | (GMT+11:00) 馬加丹 |
| 284 | (GMT+12:00) 國際標準時間+12 |
| 285 | (GMT+12:00) 斐濟 |
| 290 | (GMT+12:00) 奧克蘭、威靈頓 |
| 295 | (GMT+12:00) 阿納底，彼得保羅夫斯克-堪察加斯克 |
| 299 | (GMT+12:45) 查塔姆群島 |
| 300 | (GMT+13:00) 努瓜婁發 |
| 301 | (GMT-05:00) 切圖馬爾 |
| 302 | (UTC+02:00) 喀土穆 |
| 303 | (GMT-03:00) 蓬塔阿雷納斯 |
| 304 | (GMT+04:00) 伏爾加格勒 |
| 305 | (GMT-07:00) 育空 |