建立自定義整合，以同步您的員工管理系統與 Shifts

發行項
11/18/2024
適用於:

Microsoft Teams, Microsoft 365 for frontline workers

概觀

整合 Shifts，這是 Microsoft Teams 中的排程管理應用程式，與您的員工管理 (WFM) 系統。這項整合可讓您的一線員工直接在 Shifts 內檢視及管理其排程。

本文將引導您瞭解如何使用Microsoft 圖形 API 來建立連接器，以促進此整合。

您可以設定單向資料同步或雙向資料同步的整合。

單向同步 (WFM 系統到 Shifts) ：在此設定中，WFM 系統中的排程數據會同步至 Shifts。連接器會讀取您 WFM 系統中的數據，並將其寫入 Shifts。不過，使用者在 Shifts 中所做的任何變更，並不會反映在您的 WFM 系統中。
雙向同步 (WFM 系統和 Shifts) ：此設定允許雙向同步處理。WFM 系統中的排程數據會同步至 Shifts，而且使用者在 Shifts 中所做的任何變更都會同步回您的 WFM 系統。連接器會根據您 WFM 系統強制執行的商務規則，在將變更寫入 Shifts 之前，驗證並核准使用者在 Shifts 中所做的變更。

注意事項

如果您使用 UKG Pro WFM、Blue Yonder WFM 或 Reflexis WFM，您也可以使用受控連接器來整合 Shifts 與 WFM 系統。若要深入瞭解，請參閱 Shifts 連接器。

本文中使用的術語

術語	描述
連接器	在您的 WFM 系統與 Shifts 之間同步排程數據的應用程式。
員工整合	實體，定義通訊的加密方法、連接器的回呼 URL，以及要同步處理的 Shifts 實體。

開始之前

必要條件

根據您的業務需求判斷您想要同步的數據。
瞭解 Microsoft 身分識別平台中的驗證和授權概念。請參閱驗證和授權基本概念。
管理員必要角色：
- 至少要有雲端應用程式管理員在 Microsoft Entra 系統管理中心中註冊應用程式
- 註冊員工整合的全域管理員

熟悉整合流程

以下是整合步驟的概觀。檢閱此資訊以了解整體程式，包括執行每個步驟的人員。

步驟	單向同步	雙向同步處理	執行此步驟的人員
1	建立您的連接器：步驟 1a：將班次中所做的變更同步處理至 WFM 系統實作 /connect 端點實作 /update 端點，並將Shifts設為唯讀步驟 1b：將數據從 WFM 系統同步至 Shifts	建立您的連接器：步驟 1a：將班次中所做的變更同步處理至 WFM 系統實作 /connect 端點實作 /update 端點步驟 1b：將數據從 WFM 系統同步至 Shifts	Developer
2	在 Microsoft Entra 系統管理中心中註冊應用程式	在 Microsoft Entra 系統管理中心中註冊應用程式	至少是雲端應用程式管理員的帳戶
3	建立用於同步處理的小組和排程	建立用於同步處理的小組和排程	開發人員或 Teams 系統管理員
4	註冊並啟用員工整合：步驟 4a：在您的租用戶中註冊員工整合步驟 4b：為小組排程啟用員工整合	註冊並啟用員工整合：步驟 4a：在您的租用戶中註冊員工整合步驟 4b：為小組排程啟用員工整合	步驟 4a：全域管理員步驟 4b：開發人員

步驟 1：建立連接器

若要建立連接器，請完成下列步驟：

步驟 1a：將班次中所做的變更同步處理至 WFM 系統
步驟 1b：將數據從 WFM 系統同步至 Shifts

步驟 1a：將班次中所做的變更同步處理至 WFM 系統

若要設定連接器以接收和處理來自 Shifts 的要求，您需要實作下列端點：

/connect (必要)
/update (必要)
/read (選用)

判斷您的基底 URL 和端點 URL

webhook) (基底 URL 是 {url}/v{apiVersion}，其中 url 和 apiVersion 是您在註冊員工整合時，於 workforceIntegration 物件中設定的屬性。

端點 URL 的相對路徑如下：

/連接： /connect
/更新： /teams/{teamid}/update
/讀： /teams/{teamid}/read

例如，如果 url 為 https://contosoconnector.com/wfi ， 且 apiVersion 為 1：

基底 URL 為 https://contosoconnector/com/wfi/v1。
/connect 端點是 https://contosoconnector/wfi/v1/connect。
/update 端點為 https://contosoconnector/wfi/v1/teams/{teamid}/update。
/read 端點為 https://contosoconnector/wfi/v1/teams/{teamid}/read。

加密

所有要求都會使用 AES-256-CBC-HMAC-SHA256 加密。註冊員工整合時，您可以指定共用的秘密密鑰。傳回 Shifts 的回應不應加密。

端點

POST /connect

Shifts 會呼叫此端點，以在您註冊員工整合時測試連線。只有當此端點傳回 HTTP 200 OK 回應時，才會傳回成功回應。

範例

請求
ConnectRequest

{
   "tenantId": "a1s2s355-a2s3-j7h6-f4d3-k2h9j4mqpz",
   "userId": "4fbc12d7-1234-56ef-8a90-bc123d45678f"
}

回應
傳回 HTTP 200 OK

POST /teams/{teamid}/update

班次會呼叫此端點，以在針對員工整合啟用的排程中對 Shifts 實體進行變更時取得核准。如果此端點核准要求，變更會儲存在 Shifts 中。

因為您的 WFM 系統是記錄系統，所以當連接器收到此端點的要求時，應該先嘗試在 WFM 系統中進行變更。如果變更成功，則傳回成功。否則，傳回失敗。

Shifts 會針對每個變更 (呼叫此端點，包括從連接器/WFM 系統) 起始的變更。如果連接器使用圖形 API 將更新傳送至 Shifts 並新增X-MS-WFMPassthrough: workforceIntegratonId標頭，則此端點的要求將會具有相同的標頭，可讓您適當地識別和處理這些要求。例如，傳回成功，而不會在 WFM 系統中進行與備援相同的變更，而且可能導致連接器停滯在無限迴圈中。

下圖顯示數據流。

注意事項

如需要求和回應模型的詳細資訊，請參閱本文的端點參考一節中的 WfiRequest。

傳回回應碼
從整合的任何回應，包括錯誤，都必須有 HTTP 回應碼 200 OK。回應本文必須具有反映適當子呼叫錯誤狀態的狀態和錯誤訊息。整合以外的 200 OK 任何回應都會視為錯誤，並傳回給呼叫端 (用戶端或 Microsoft Graph) 。

如果您想要設定單向同步處理，請將 Shifts 設為唯讀

若要進行單向同步處理，您必須將 Shifts 設為唯讀，讓使用者無法在 Shifts 中進行變更。若要讓 Shifts 成為唯讀，請傳回 Shifts 中所有要求的失敗回應。

例如，若要封鎖用戶變更排程中的班次，此端點必須在每次收到實體相關 shift 要求時傳回失敗回應。

範例

請求
WfiRequestContainer

下列範例顯示Shifts的要求，詢問標識符為 SHFT_12345678-1234-1234-1234-1234-1234567890ab且屬性列在本文中，是否可以儲存在Shifts中。當使用者在 Shifts 中建立班次時，就會觸發此要求。

{
  "requests": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "method": "POST",
      "url": "/shifts/SHFT_12345678-1234-1234-1234-1234567890ab",
      "headers": {
        "X-MS-Transaction-ID": "1",
        "X-MS-Expires": "2024-10-11T21:27:59.0134605Z"
      },
      "body": {
        "draftShift": {
          "activities": [],
          "isActive": true,
          "startDateTime": "2024-10-12T15:00:00.000Z",
          "endDateTime": "2024-10-12T17:00:00.000Z",
          "theme": "Blue"
        },
        "isStagedForDeletion": false,
        "schedulingGroupId": "TAG_a3e0b3f1-4a5c-4c2e-8eeb-5b8c3d1e3f8b",
        "userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "createdDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedBy": {
          "user": {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "displayName": "Adele Vance"
          }
        },
        "id": "SHFT_12345678-1234-1234-1234-1234567890ab"
      }
    }
  ]
}

回應
WfiResponse

成功：傳回 HTTP 200 OK

此範例顯示端點核准要求時所傳回的回應。在此案例中，班次會儲存在 Shifts 中，而使用者可以看到排程中的班次。

{
  "responses": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "status": 200,
      "body": {
        "eTag": "3f4e5d6c-7a8b-9c0d-1e2f-3g4h5i6j7k8l",
        "error": null,
        "data": null
      }
    }
  ]
}

失敗：傳回 HTTP 200 OK

此範例顯示端點拒絕要求時所傳回的回應。在此案例中，使用者會在 Shifts 中收到「無法新增班次」錯誤訊息。

{
    "responses": [
        {
            "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
            "status": 500,
            "body": {
                "error": {
                    "code": "500",
                    "message": “Could not add the shift”
                },
                "data": null
            }
        }
    ]
}

POST /teams/{teamid}/read

此端點會處理來自 Shifts 的要求，以擷取符合資格的逾時原因或適用於使用者交換要求的合格輪班。

注意事項

自 2024 年 10 月起，只有 beta 版本的 Microsoft 圖形 API 才支援此端點。當您註冊員工整合時，也必須指定 eligibilityFilteringEnabledEntities 屬性的值。

下圖顯示數據流。

傳回回應碼
從整合的任何回應，包括錯誤，都必須有 HTTP 回應碼 200 OK。回應本文必須包含反映適當子呼叫錯誤狀態的狀態和錯誤訊息。整合以外的 200 OK 任何回應都會視為錯誤，並傳回給呼叫端 (用戶端或 Microsoft Graph) 。

範例：TimeOffReason

請求

下列範例顯示Shifts的要求，詢問使用者 (用戶標識碼 aa162a04-bec6-4b81-ba99-96caa7b2b24d) 符合資格的逾時原因。當使用者在 Shifts 中要求休假時，就會觸發此要求。

 { 
  "requests": [ 
    { 
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
      "method": "GET", 
      "url": "/users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason"
    } 
  ] 
}

回應
成功：傳回 HTTP 200 OK

下列回應顯示使用者的合格休假原因標識符為 “TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc” 和 “TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d”。在此案例中，使用者會看到在 Shifts 中選擇的對應逾時原因。

{
    "responses": [ 
      { 
        "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
        "status": 200, 
        "body": { 
          "data": [ 
            "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc", 
            "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d" 
          ], 
          "error": null 
          } 
        }
    ]
}

失敗：傳回 HTTP 200 OK

在此範例中，會傳回錯誤回應，因為連接器無法連線到 WFM 系統來擷取使用者的休假原因。

 {
  "responses": [
    {
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "Could not reach WFM"
        }
      }
    }
  ]
}

範例：SwapRequest

請求

下列範例顯示Shifts的要求，該要求會詢問哪些班次有資格與標識碼為 SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 的班次交換，介於 2024-2024-1 10-01T04：00：00.00000000Z 和 2024-11-01T03：59：59.99900000Z。

{
  "requests": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "method": "GET",
      "url": "/shifts/SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029/requestableShifts?requestType=SwapRequest&startTime=2024-10-01T04:00:00.0000000Z&endTime=2024-11-01T03:59:59.9990000Z"
    }
  ]
}

回應
成功：傳回 HTTP 200 OK

下列回應顯示班次可以與標識碼為 SHFT_98e96e23-966b-43be-b90d-4697037b67af 的班次交換。

{ 
  "responses": [ 
    { 
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029", 
      "status": 200, 
      "body": { 
        "data": ["SHFT_98e96e23-966b-43be-b90d-4697037b67af"],
        "error": null, 
      } 
    }
  ]
}

失敗：傳回 HTTP 200 OK

在此範例中，會傳回錯誤回應，因為連接器無法連線到 WFM 系統，以擷取使用者交換要求的合格班次。

{
  "responses": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "could not reach WFM"
        }
      }
    }
  ]
}

步驟 1b：將數據從您的 WFM 系統同步至 Shifts

使用 Microsoft Graph 中的 Shifts API 從您的 WFM 系統讀取排程數據，並將數據寫入 Shifts。

例如，若要將班次新增至 Shifts，請使用建立班次 API。

請參閱 Shifts API 的 Microsoft 圖形 API v1.0 參考，其列在 Shift 管理之下。

注意事項

此 MS-APP-ACTS-AS 標頭在要求中是必要的，而且必須包含您應用程式代表之使用者的標識碼 (GUID) 。建議您在更新排程時使用小組擁有者的使用者識別碼。

下圖顯示數據流。

初始同步處理

針對第一次同步處理，連接器應該讀取您 WFM 系統中的數據，並將數據寫入 Shifts。建議您在未來兩周同步處理數據。

初始同步處理之後

第一次同步處理之後，您可以選擇：

使用您 WFM 系統中的變更同步更新 Shifts：針對您 WFM 系統中所做的每項變更，將更新傳送至 Shifts。
使用 WFM 系統中的變更異步更新 Shifts：撰寫 WFM 系統在特定時間範圍內發生的所有變更，以執行定期同步處理 (例如，) 移位 10 分鐘。

所有 Shifts 的寫入作業，包括連接器起始的寫入作業，都會觸發對連接器 /update 端點的呼叫。建議您將標頭包含 X-MS-WFMPassthrough: workforceIntegratonId 在所有寫入呼叫中，讓連接器可以適當地識別和處理它們。例如，如果您的 WFM 系統起始變更，請核准它，而不將更新套用至您的 WFM 系統。

注意事項

如果您要針對 WFM 系統與 Shifts 之間的雙向數據同步設定連接器，請在定期同步處理中排除從 Shifts 起始的變更。這些變更已以Shifts撰寫。

步驟 2：在 Microsoft Entra 系統管理中心中註冊應用程式

請遵循下列步驟，在 Microsoft 身分識別平台中為您的連接器註冊應用程式、設定應用程式存取 Microsoft Graph 的許可權，以及取得存取令牌。

至少以雲端應用程式管理員身分登入 Microsoft Entra 系統管理中心。
註冊您的應用程式。如需步驟，請參閱向 Microsoft 身分識別平台註冊應用程式。
將 Schedule.ReadWrite.All 應用程式許可權指派給應用程式以進行僅限應用程式存取，並取得存取令牌。

如需逐步指引，請參閱在沒有用戶的情況下取得存取權。

存取令牌會使用 Schedule.ReadWrite.All 許可權，驗證您的應用程式是否有權使用自己的身分識別來呼叫 Microsoft Graph。它必須包含在要求的授權標頭中。

步驟 3：建立小組和排程以進行同步處理

在 Teams 中設定您想要同步的團隊。您可以使用現有的小組或建立新的小組。

在 Teams 中設定小組，以與您 WFM 系統中的小組和位置對應。請確定您將下列人員新增至每個小組：
- 以團隊擁有者身分擔任一線經理。請務必將標頭中的 MS-APP-ACTS-AS 使用者新增為每個個別小組的小組擁有者。
- 以團隊成員身分的第一線員工。
為每個小組在Shifts中建立排程。若要深入瞭解，請參閱建立或取代排程。
將排程群組新增至每個小組的排程。排程群組可用來根據小組內的常見特性將員工分組。例如，排程群組可以是部門或作業類型。若要深入瞭解，請參閱排程群組資源類型。
將員工新增至每個排程群組。若要深入瞭解，請參閱取代 schedulingGroup。

注意事項

您也可以使用Teams系統管理中心來設定您的團隊，並將Shifts部署到小組。若要深入了解，請參閱：

步驟 4：註冊並啟用員工整合

員工整合會定義 Shifts 與連接器之間通訊的加密設定、Shifts 回呼的 URL，以及要同步處理的實體類型。

若要註冊並啟用員工整合，請完成下列步驟：

步驟 4a：註冊員工整合
步驟 4b：為小組排程啟用員工整合

步驟 4a：在您的租用戶中註冊員工整合

您必須是全域管理員才能執行此步驟。

使用建立 workforceIntegration API 在您的租用戶中註冊您的員工整合。

以下是要求的範例。

POST https://graph.microsoft.com/v1.0/teamwork/workforceIntegrations/
{ 
  "displayName": "Contoso integration", 
  "apiVersion": 1, 
  "encryption": { 
    "protocol": "sharedSecret", 
    "secret": "secret-value" 
  }, 
  "isActive": true, 
  "url": "https://contosoconnector.com/wfi", 
  "supportedEntities": "Shift,SwapRequest,UserShiftPreferences,Openshift,OpenShiftRequest,OfferShiftRequest”,
}

如需詳細資料，請參閱下列表格。若要深入瞭解，請參閱 workforceIntegration 資源類型。

Property	其他相關資訊
apiVersion	回呼 URL 的 API 版本。您的基底 URL 是由 url 屬性和這個屬性所組成。
加密	將通訊協定設定為 `sharedSecret`。秘密值必須剛好是64個字元。使用秘密來解密從 Shifts 傳送至連接器端點的加密 JSON 承載。承載會使用 AES-256-CBC-HMAC-SHA256 加密。您的應用程式應該安全地保存此秘密。例如，在金鑰保存庫中。
supportedEntities	指定您希望連接器支援同步處理的 Shifts 實體。當其中任何一個實體變更時，Shifts 會呼叫連接器的 /update 端點，讓您可以核准或拒絕變更。如需可能值的清單，請參閱 workforceIntegration 資源類型注意此清單是可演化的列舉。您必須使用 `Prefer: include-unknown-enum-members` 要求標頭來取得所有值。
eligibilityFilteringEnabledEntities	注意：自 2024 年 10 月起，只有 beta 版本的 Microsoft 圖形 API 才支援此端點。指定您想要連接器以支援資格篩選的 Shifts 實體。可能的值為： `none`：空白清單 `SwapRequests`：Shifts 會呼叫連接器的 /read 端點，以取得篩選的班次清單，讓使用者可以選擇交換要求。 `TimeOffReasons`：Shifts 會呼叫連接器的 /read 端點，以取得篩選的逾時原因清單，讓使用者在要求休假時可以選擇。注意此清單是可演化的列舉。您必須使用 `Prefer: include-unknown-enum-members` 要求標頭來取得所有值。
URL	從 Shifts 回呼的員工整合 URL。您的基底 URL 是由這個屬性和 apiVerson 屬性所組成。

步驟 4b：為小組排程啟用員工整合

根據您想要管理的排程來啟用您的員工整合。若要這樣做，請使用建立或取代排程 API 來建立或更新小組的排程。

以下是要求的範例。

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}

指定當您註冊員工整合時所產生的 workforceIntegrationId。
您可以依排程最多啟用一個員工整合。如果您在要求中包含一個以上的 workforceIntegrationId，則會使用第一個。

疑難排解

連接器

當連接器回應 Shifts 的要求時，如果傳回 200 以外的回應碼，會發生什麼事？如果它在回應本文中傳回 200 以外的狀態，是否會產生差異？

這兩種案例之間有差異。

如果連接器傳回 200 以外的響應碼，Shifts 會嘗試重試 /read 和 /update 端點多次。最後，Shifts 會顯示「發生錯誤。小組上的員工整合設定已回應無效的數據。」錯誤訊息。
如果連接器在回應本文中傳回 200 以外的狀態，Shifts 會顯示「發生錯誤。很抱歉，您的變更無法完成。」錯誤訊息，並停止重試端點。

如果連接器在回應本文中傳回無效的數據，會發生什麼事？

Shift 會嘗試重試 /read 和 /update 端點多次。最後，Shifts 會顯示「發生錯誤。您小組上設定的員工整合已回應無效的數據。」錯誤訊息。

如何? 識別要求最初是在 Shifts 還是 WFM 系統中提出，以防止無限迴圈？

X-MS-WFMPassthrough: workforceIntegratonId將標頭新增至所有寫入和更新呼叫，以識別/忽略連接器所觸發的變更。此標頭用來表示發出要求是因為連接器先前對圖形 API 發出的呼叫，以將數據從您的 WFM 系統同步至 Shifts。

員工整合註冊

我註冊了員工整合，並指定了 “eligibilityFilteringEnabledEntities”，包括 “SwapRequest、OfferShiftRequest 和 TimeOffReason”，但回應本文不會顯示 [資格][資格][篩選][可完成]清單。

目前支援 https://graph.microsoft.com/beta 透過端點進行資格篩選，而非 https://graph.microsoft.com/v1 端點。

我註冊了員工整合並新增了 “supportedEntities”，但收到 400 不正確的要求回應和「無效的承載：要求的值 'shift， ....' 找不到。」訊息

請確定清單要求本文中的 supportedEntities 每個 Shifts 實體都是以大寫字母開頭。例如，"supportedEntities":"Shift,SwapRequest,OpenShift"。

我已註冊員工整合並實作 /connect、/update 和 /read 端點，但 Webhook 無法運作。

確定已針對小組排程啟用您的員工整合。此外，請檢查 URL 和 apiVersion 屬性是否正確。

端點參考

請求

ConnectRequest

屬性	類型	描述
tenantId	字串	員工整合的租用戶標識碼
userId	字串	員工整合的使用者標識碼

{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

屬性	類型	描述
請求	WfiRequest 集合	WfiRequests 清單

{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

要求中的元素數目：

在大部分情況下，要求有一個元素。
某些要求，例如交換班次要求核准，有五個元素：一個 PUT 交換要求、兩個 DELETE 班次 (現有的班次) ，以及兩個 POST 班次 (新的班次) 。

WfiRequest

屬性	類型	描述
id	字串	實體的標識碼
方法	字串	在專案上叫用的方法。例如，、`POSTPUT`、、。`GETDELETE`
URL	字串	指出實體和作業詳細數據的類型。
頭	WfiRequestHeader	標頭
body	ShiftsEntity	與要求相關的實體主體。

適用於 POST /teams/{teamId}/update

屬性	類型	描述
id	字串	實體的標識碼
方法	字串	`POST` 若要建立實體， `PUT` 則更新實體， `DELETE` 以刪除實體。
URL	字串	格式為 `/{EntityType}/{EntityId}`。的可能值`{EntityType}`為 `shifts`、`swapRequests`、`timeoffReasons`、、`openshifts`、`openshiftrequests`、、`timesoffoffershiftrequests`、 `timeOffRequests`。例如，`/shifts/SHFT_12345678-1234-1234-1234-1234567890ab`。
頁眉	WfiRequestHeader	頁首
body	ShiftsEntity	必須在url屬性中比`{EntityType}`對。使用其中一個 shift、 swapShiftsChangeRequest、 timeOffReason、 openshift、 openShiftChangeRequest、 offerShiftRequests、 timeOff、 timeOffRequest。例如，`/shifts/SHFT_12345678-1234-1234-1234-1234567890ab`。

若為 POST /teams/{teamsId}/read

屬性	類型	描述
id	字串	實體的標識碼
方法	字串	一律 `GET`為。
URL	字串	TimeOffReasons：格式為 `/users/{userId}/timeOffReasons?requestType=TimeOffReason`。例如，`/users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason`。 SwapRequest：格式為 `/shifts/{ShiftsId}/requestableShifts?requestType=SwapRequest\u0026startTime={startTime}\u0026endTime={endTime}`。例如，`shifts/SHFT_1132430e-365e-4dc5-b8b0-b800592a81a8/requestableShifts?requestType=SwapRequest\u0026startTime=2024-10-01T07:00:00.0000000Z\u0026endTime=2024-11-01T06:59:59.9990000Z`。
頁眉	WfiRequestHeader	頁首
body	ShiftsEntity	一律 `null`為。

WfiRequestHeader

屬性	類型	描述
X-MS-Transaction-ID	字串	交易標識碼
X-MS-Expires	DateTime (字串)	交易到期日期時間

X-MS-WFMPassthrough: workforceIntegratonId 不會包含在 WfiRequestHeader 中。它應該從 HttpRequest 中擷取。

回應

WfiResponseContainer

屬性	類型	描述
反應	WfiResponse 集合	WfiResponses 清單

{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

屬性	類型	描述
id	字串	實體的標識碼
狀態	字串	作業的結果
body	WfiResponseBody	WfiResponseBody

WfiResponseBody

屬性	類型	描述
eTag	字串	eTag
錯誤	WfiResponseError	錯誤的詳細數據
資料	字串	讀取要求的要求數據 ()

WfiResponseError

屬性	類型	描述
code	字串	錯誤碼
訊息	字串	錯誤訊息

共用方式為

建立自定義整合，以同步您的員工管理系統與 Shifts

概觀

本文中使用的術語

開始之前

必要條件

熟悉整合流程

步驟 1：建立連接器

步驟 1a：將班次中所做的變更同步處理至 WFM 系統

端點

POST /connect

範例

POST /teams/{teamid}/update

如果您想要設定單向同步處理，請將 Shifts 設為唯讀

範例

POST /teams/{teamid}/read

範例：TimeOffReason

範例：SwapRequest

步驟 1b：將數據從您的 WFM 系統同步至 Shifts

初始同步處理

初始同步處理之後

步驟 2：在 Microsoft Entra 系統管理中心 中註冊應用程式

步驟 3：建立小組和排程以進行同步處理

步驟 4：註冊並啟用員工整合

步驟 4a：在您的租用戶中註冊員工整合

步驟 4b：為小組排程啟用員工整合

疑難排解

連接器

當連接器回應 Shifts 的要求時，如果傳回 200 以外的回應碼，會發生什麼事？ 如果它在回應本文中傳回 200 以外的狀態，是否會產生差異？

如果連接器在回應本文中傳回無效的數據，會發生什麼事？

如何? 識別要求最初是在 Shifts 還是 WFM 系統中提出，以防止無限迴圈？

員工整合註冊

我註冊了員工整合，並指定了 “eligibilityFilteringEnabledEntities”，包括 “SwapRequest、OfferShiftRequest 和 TimeOffReason”，但回應本文不會顯示 [資格][資格][篩選][可完成]清單。

我註冊了員工整合並新增了 “supportedEntities”，但收到 400 不正確的要求回應和「無效的承載：要求的值 'shift， ....' 找不到。」 訊息

我已註冊員工整合並實作 /connect、/update 和 /read 端點，但 Webhook 無法運作。

端點參考

請求

ConnectRequest

WfiRequestContainer

WfiRequest

適用於 POST /teams/{teamId}/update

若為 POST /teams/{teamsId}/read

WfiRequestHeader

回應

WfiResponseContainer

WfiResponse

WfiResponseBody

WfiResponseError

相關文章

意見反應

其他資源

步驟 2：在 Microsoft Entra 系統管理中心中註冊應用程式

當連接器回應 Shifts 的要求時，如果傳回 200 以外的回應碼，會發生什麼事？如果它在回應本文中傳回 200 以外的狀態，是否會產生差異？

我註冊了員工整合並新增了 “supportedEntities”，但收到 400 不正確的要求回應和「無效的承載：要求的值 'shift， ....' 找不到。」訊息