Shifts와 인력 관리 시스템을 동기화하는 사용자 지정 통합 만들기

아티클
11/18/2024
적용 대상:

Microsoft Teams, Microsoft 365 for frontline workers

개요

Microsoft Teams의 일정 관리 앱인 Shifts를 WFM(인력 관리) 시스템과 통합합니다. 이 통합을 통해 최전방 직원은 Shifts 내에서 직접 일정을 보고 관리할 수 있습니다.

이 문서에서는 이 통합을 용이하게 하기 위해 Microsoft Graph API 사용하여 커넥터를 만드는 방법을 안내합니다.

단방향 데이터 동기화 또는 양방향 데이터 동기화에 대한 통합을 설정할 수 있습니다.

단방향 동기화(WFM 시스템을 Shifts로): 이 설정에서 WFM 시스템의 예약 데이터는 Shifts에 동기화됩니다. 커넥터는 WFM 시스템에서 데이터를 읽고 Shifts에 씁니다. 그러나 사용자가 Shifts에서 변경한 내용은 WFM 시스템에 다시 반영되지 않습니다.
양방향 동기화(WFM 시스템 및 Shifts): 이 설정을 통해 양방향 동기화를 수행할 수 있습니다. WFM 시스템의 일정 데이터가 Shifts에 동기화되고 사용자가 Shifts에서 변경한 내용이 WFM 시스템에 다시 동기화됩니다. 커넥터는 변경 내용이 Shifts에 기록되기 전에 WFM 시스템에서 적용되는 비즈니스 규칙에 따라 사용자가 Shifts에서 수행한 변경 내용의 유효성을 검사하고 승인합니다.

참고

UKG Pro WFM, Blue Yonder WFM 또는 Reflexis WFM 사용하는 경우 관리형 커넥터를 사용하여 Shifts를 WFM 시스템과 통합할 수도 있습니다. 자세한 내용은 Shifts 커넥터를 참조하세요.

이 문서에서 사용되는 용어

용어	설명
커넥터	WFM 시스템과 Shifts 간에 일정 데이터를 동기화하는 앱입니다.
인력 통합	통신을 위한 암호화 방법, 커넥터의 콜백 URL 및 동기화할 Shifts 엔터티를 정의하는 엔터티입니다.

시작하기 전에

필수 구성 요소

비즈니스 요구 사항에 따라 동기화할 데이터를 결정합니다.
Microsoft ID 플랫폼 인증 및 권한 부여 개념을 이해합니다. 인증 및 권한 부여 기본 사항을 참조하세요.
관리 역할 필요:
- Microsoft Entra 관리 센터 앱을 등록할 클라우드 애플리케이션 관리자 이상
- 전역 관리자가 인력 통합을 등록합니다.

통합 프로세스 숙지

통합 단계에 대한 개요는 다음과 같습니다. 이 정보를 검토하여 각 단계를 수행하는 사람을 포함하여 전체 프로세스를 이해합니다.

단계	단방향 동기화	양방향 동기화	이 단계를 수행하는 사람
1	커넥터 만들기: 1a단계: Shifts의 변경 내용을 WFM 시스템에 동기화 /connect 엔드포인트 구현 엔드포인트 /update를 구현하고 Shifts를 읽기 전용으로 만들기 1b단계: WFM 시스템에서 Shifts로 데이터 동기화	커넥터 만들기: 1a단계: Shifts의 변경 내용을 WFM 시스템에 동기화 /connect 엔드포인트 구현 엔드포인트 구현/업데이트 1b단계: WFM 시스템에서 Shifts로 데이터 동기화	Developer
2	Microsoft Entra 관리 센터 앱 등록	Microsoft Entra 관리 센터 앱 등록	클라우드 애플리케이션 관리자 이상의 계정
3	동기화를 위한 팀 및 일정 만들기	동기화를 위한 팀 및 일정 만들기	개발자 또는 Teams 관리자
4	인력 통합을 등록하고 사용하도록 설정합니다. 4a단계: 테넌트에서 인력 통합 등록 4b단계: 팀 일정에 대한 인력 통합 사용	인력 통합을 등록하고 사용하도록 설정합니다. 4a단계: 테넌트에서 인력 통합 등록 4b단계: 팀 일정에 대한 인력 통합 사용	4a단계: 전역 관리자 4b단계: 개발자

1단계: 커넥터 만들기

커넥터를 만들려면 다음 단계를 완료합니다.

1a단계: Shifts의 변경 내용을 WFM 시스템에 동기화
1b단계: WFM 시스템에서 Shifts로 데이터 동기화

1a단계: Shifts의 변경 내용을 WFM 시스템에 동기화

Shifts에서 요청을 수신하고 처리하도록 커넥터를 설정하려면 다음 엔드포인트를 구현해야 합니다.

/connect (필수)
/update (필수)
/read (선택 사항)

기본 URL 및 엔드포인트 URL 확인

기본 URL(webhook)은 입니다{url}/v{apiVersion}. 여기서 url 및 apiVersion은 workforce 통합을 등록할 때 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.

Encryption

모든 요청은 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 엔터티를 변경할 때 승인을 받습니다. 이 엔드포인트가 요청을 승인하면 변경 내용이 Shifts에 저장됩니다.

WFM 시스템은 레코드 시스템이므로 커넥터가 이 엔드포인트에 대한 요청을 받으면 먼저 WFM 시스템을 변경하려고 시도해야 합니다. 변경에 성공하면 성공을 반환합니다. 그렇지 않으면 실패를 반환합니다.

Shifts는 모든 변경(커넥터/WFM 시스템에서 시작된 변경 내용 포함)에 대해 이 엔드포인트를 호출합니다. 커넥터가 Graph API 사용하여 Shifts에 업데이트를 보내고 헤더를 추가 X-MS-WFMPassthrough: workforceIntegratonId 한 경우 이 엔드포인트로 들어오는 요청에는 동일한 헤더가 있으므로 이러한 요청을 적절하게 식별하고 처리할 수 있습니다. 예를 들어 WFM 시스템에서 동일한 변경을 하지 않고 성공을 반환하면 중복되고 커넥터가 무한 루프에서 중단될 수 있습니다.

다음 다이어그램은 데이터 흐름을 보여줍니다.

참고

요청 및 응답 모델에 대한 자세한 내용은 이 문서의 엔드포인트 참조 섹션에서 WfiRequest를 참조하세요.

응답 코드 반환
오류를 포함하여 통합의 모든 응답에는 HTTP 응답 코드 200 OK가 있어야 합니다. 응답 본문에는 적절한 하위 호출 오류 상태를 반영하는 상태 및 오류 메시지가 있어야 합니다. 이외의 통합 200 OK 의 모든 응답은 오류로 처리되고 호출자(클라이언트 또는 Microsoft Graph)에게 반환됩니다.

단방향 동기화를 설정하려면 Shifts를 읽기 전용으로 만듭니다.

단방향 동기화의 경우 사용자가 Shifts를 변경할 수 없도록 Shifts를 읽기 전용으로 만들어야 합니다. Shifts를 읽기 전용으로 만들려면 Shifts의 모든 요청에 대한 오류 응답을 반환합니다.

예를 들어 사용자가 일정에서 교대 근무를 변경하지 못하도록 차단하려면 이 엔드포인트는 엔터티에 대한 shift 요청을 받을 때마다 실패 응답을 반환해야 합니다.

예제

요청
WfiRequestContainer

다음 예제에서는 ID가 SHFT_12345678-1234-1234-1234-1234567890ab이고 본문에 나열된 속성이 있는 교대 근무를 Shifts에 저장할 수 있는지 여부를 묻는 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월부터 이 엔드포인트는 Microsoft Graph API 베타 버전에서만 지원됩니다. 또한 인력 통합을 등록할 때 eligibilityFilteringEnabledEntities 속성에 대한 값을 지정해야 합니다.

다음 다이어그램은 데이터 흐름을 보여줍니다.

응답 코드 반환
오류를 포함하여 통합의 모든 응답에는 HTTP 응답 코드 200 OK가 있어야 합니다. 응답 본문에는 적절한 하위 호출 오류 상태를 반영하는 상태 및 오류 메시지가 포함되어야 합니다. 이외의 통합 200 OK 의 모든 응답은 오류로 처리되고 호출자(클라이언트 또는 Microsoft Graph)에게 반환됩니다.

예: TimeOffReason

요청

다음 예제에서는 사용자가 사용할 수 있는 시간(사용자 ID aa162a04-bec6-4b81-ba99-96caa7b2b24d)을 요청하는 Shifts의 요청을 보여 줍니다. 이 요청은 사용자가 Shifts에서 휴가를 요청할 때 트리거되었습니다.

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

응답
성공: HTTP 반환 200 OK

다음 응답은 사용자에 대한 적격 오프 이유 ID가 "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

요청

다음 예제에서는 2024-2024 사이의 ID가 SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029인 교대 근무와 교환할 수 있는 교대 근무를 묻는 Shifts의 요청을 보여 줍니다. 10-01T04:00:00.0000000Z 및 2024-11-01T03:59:59.9990000Z.

{
  "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

다음 응답은 ID가 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에 교대 근무를 추가하려면 Shift API 만들기 를 사용합니다.

Shift 관리 아래에 나열된 Shifts API에 대한 Microsoft Graph API v1.0 참조를 참조하세요.

참고

헤더는 MS-APP-ACTS-AS 요청에 필요하며 앱이 대신 작업하는 사용자의 ID(GUID)를 포함해야 합니다. 일정을 업데이트할 때 팀 소유자의 사용자 ID를 사용하는 것이 좋습니다.

다음 다이어그램은 데이터 흐름을 보여줍니다.

초기 동기화

첫 번째 동기화의 경우 커넥터는 WFM 시스템의 데이터를 읽고 Shifts에 데이터를 써야 합니다. 향후 2주간의 데이터를 동기화하는 것이 좋습니다.

초기 동기화 후

첫 번째 동기화 후에 다음을 선택할 수 있습니다.

WFM 시스템의 변경 내용으로 Shifts를 동기적으로 업데이트: WFM 시스템에서 변경된 모든 변경 내용에 대해 Shifts에 업데이트를 보냅니다.
WFM 시스템의 변경 내용으로 Shifts를 비동기적으로 업데이트: 특정 기간(예: 10분) 내에 WFM 시스템에서 발생한 모든 변경 내용을 Shifts에 기록하여 주기적인 동기화를 수행합니다.

커넥터에서 시작한 쓰기 작업을 포함하여 Shifts에 대한 모든 쓰기 작업은 커넥터의 /update 엔드포인트에 대한 호출을 트리거합니다. 커넥터가 X-MS-WFMPassthrough: workforceIntegratonId 적절하게 식별하고 처리할 수 있도록 모든 쓰기 호출에 헤더를 포함하는 것이 좋습니다. 예를 들어 WFM 시스템에서 변경을 시작한 경우 WFM 시스템에 업데이트를 적용하지 않고 승인합니다.

참고

WFM 시스템과 Shifts 간에 양방향 데이터 동기화를 위해 커넥터를 설정하는 경우 주기적 동기화에서 Shifts에서 시작된 변경 내용을 제외합니다. 이러한 변경 내용은 이미 Shifts에 기록되어 있습니다.

2단계: Microsoft Entra 관리 센터 앱 등록

다음 단계에 따라 Microsoft ID 플랫폼 커넥터에 대한 앱을 등록하고, 앱이 Microsoft Graph에 액세스하도록 권한을 구성하고, 액세스 토큰을 가져옵니다.

적어도 클라우드 애플리케이션 관리자로 Microsoft Entra 관리 센터 로그인합니다.
앱을 등록합니다. 단계는 Microsoft ID 플랫폼 애플리케이션 등록을 참조하세요.
앱 전용 액세스를 위해 Schedule.ReadWrite.All애플리케이션 권한을 앱에 할당하고 액세스 토큰을 가져옵니다.

단계별 지침은 사용자 없이 액세스 가져오기를 참조하세요.

액세스 토큰은 앱이 Schedule.ReadWrite.All 권한을 사용하여 자체 ID를 사용하여 Microsoft Graph를 호출할 권한이 있는지 확인합니다. 요청의 권한 부여 헤더에 포함되어야 합니다.

3단계: 동기화를 위한 팀 및 일정 만들기

동기화하려는 Teams에서 팀을 설정합니다. 기존 팀을 사용하거나 새 팀을 만들 수 있습니다.

teams에서 팀을 설정하여 WFM 시스템의 팀 및 위치에 대응합니다. 각 팀에 다음 사용자를 추가해야 합니다.
- 팀 소유자로서의 최전방 관리자. 헤더에 MS-APP-ACTS-AS 사용자를 각 팀의 팀 소유자로 추가해야 합니다.
- 최전방 작업자를 팀 구성원으로 지정합니다.
각 팀에 대한 Shifts에서 일정을 만듭니다. 자세한 내용은 일정 만들기 또는 바꾸기를 참조하세요.
각 팀의 일정에 일정 그룹을 추가합니다. 일정 그룹은 팀 내의 일반적인 특성에 따라 직원을 그룹화하는 데 사용됩니다. 예를 들어 일정 그룹은 부서 또는 작업 유형일 수 있습니다. 자세한 내용은 schedulingGroup 리소스 종류를 참조하세요.
각 일정 그룹에 직원을 추가합니다. 자세한 내용은 SchedulingGroup 바꾸기를 참조하세요.

참고

Teams 관리 센터를 사용하여 팀을 설정하고 팀에 Shifts를 배포할 수도 있습니다. 자세한 내용은 다음을 참조하세요.

4단계: 인력 통합 등록 및 사용

인력 통합은 Shifts와 커넥터 간의 통신을 위한 암호화 설정, Shifts의 콜백 URL 및 동기화할 엔터티 유형을 정의합니다.

인력 통합을 등록하고 사용하도록 설정하려면 다음 단계를 완료합니다.

4a단계: 인력 통합 등록
4b단계: 팀 일정에 대한 인력 통합 사용

4a단계: 테넌트에서 인력 통합 등록

이 단계를 수행하려면 전역 관리자여야 합니다.

workforce 만들기통합 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 리소스 종류를 참조하세요.

속성	추가 정보
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월부터 이 엔드포인트는 Microsoft Graph 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를 포함하는 경우 첫 번째 workforceIntegrationId가 사용됩니다.

문제 해결

커넥터

커넥터가 Shifts의 요청에 응답하면 200이 아닌 응답 코드를 반환하면 어떻게 되나요? 응답 본문에서 200이 아닌 상태 반환하는 경우 차이가 있나요?

이러한 두 시나리오 간에는 차이가 있습니다.

커넥터가 200이 아닌 응답 코드를 반환하는 경우 Shifts는 /read 및 /update 엔드포인트를 여러 번 다시 시도합니다. 결국 Shifts는 "문제가 발생했습니다. 팀의 인력 통합 설정이 잘못된 데이터로 응답했습니다." 오류 메시지가 표시됩니다.
커넥터가 응답 본문에 200이 아닌 상태 반환하면 Shifts에 "문제가 발생했습니다. 죄송합니다. 변경 내용을 완료할 수 없습니다." 오류 메시지와 엔드포인트 재시도를 중지합니다.

커넥터가 응답 본문에 잘못된 데이터를 반환하면 어떻게 되나요?

Shifts는 /read 및 /update 엔드포인트를 여러 번 다시 시도합니다. 결국 Shifts는 "문제가 발생했습니다. 팀에 설정된 인력 통합이 잘못된 데이터로 응답했습니다." 오류 메시지가 표시됩니다.

무한 루프를 방지하기 위해 요청이 원래 Shifts 또는 WFM 시스템에서 이루어졌는지 여부를 식별할 어떻게 할까요? 있나요?

X-MS-WFMPassthrough: workforceIntegratonId 모든 쓰기 및 업데이트 호출에 헤더를 추가하여 커넥터에 의해 트리거된 변경 내용을 식별/무시합니다. 이 헤더는 커넥터가 WFM 시스템에서 Shifts로 데이터를 동기화하도록 Graph API 이전 호출로 인해 요청이 수행되었음을 나타내는 데 사용됩니다.

인력 통합 등록

인력 통합을 등록하고 "SwapRequest, OfferShiftRequest 및 TimeOffReason"을 포함하여 "eligibilityFilteringEnabledEntities"를 지정했지만 응답 본문에는 "eligibilityFilteringEnabledEntities" 목록이 표시되지 않습니다.

자격 필터링은 현재 엔드포인트가 https://graph.microsoft.com/beta 아닌 엔드포인트를 https://graph.microsoft.com/v1 통해 지원됩니다.

인력 통합을 등록하고 "supportEntities"를 추가했지만 400 잘못된 요청 응답과 "잘못된 페이로드: 요청된 값 'shift, ....'을 수신합니다. 찾을 수 없습니다." 메시지

목록 요청 본문의 모든 Shifts 엔터티가 supportedEntities 대문자로 시작하는지 확인합니다. 예를 들면 "supportedEntities":"Shift,SwapRequest,OpenShift"와 같습니다.

인력 통합을 등록하고 /connect, /update 및 /read 엔드포인트를 구현했지만 웹후크가 작동하지 않습니다.

팀 일정에 맞게 인력 통합이 사용하도록 설정되어 있는지 확인합니다. 또한 url 및 apiVersion 속성이 올바른지 검사.

엔드포인트 참조

요청

ConnectRequest

속성	유형	설명
tenantId	String	인력 통합을 위한 테넌트 ID
userId	String	인력 통합을 위한 사용자의 ID

{
  "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 교환 요청 1개, DELETE 교대 근무 2개(기존 교대 근무) 및 두 개의 POST 교대 근무(새 교대 근무)의 5가지 요소가 있습니다.

WfiRequest

속성	유형	설명
id	String	엔터티의 ID
메서드	String	항목에서 호출된 메서드입니다. 예를 들어 , `POST`, `PUT`, `GET`, 입니다 `DELETE`.
url	String	엔터티 및 작업 세부 정보의 형식을 나타냅니다.
헤더	WfiRequestHeader	머리글
몸	ShiftsEntity	요청과 관련된 엔터티의 본문입니다.

POST /teams/{teamId}/update의 경우

속성	유형	설명
id	String	엔터티의 ID
메서드	String	`POST` 엔터티를 만들고 엔 `PUT` 터티를 업데이트하여 엔터 `DELETE` 티를 삭제합니다.
url	String	형식은 입니다 `/{EntityType}/{EntityId}`. 에 사용할 `{EntityType}` 수 있는 값은 , `swapRequests`, `timeoffReasons`, `openshifts`, `openshiftrequests`, `offershiftrequests`, , `timesofftimeOffRequests`입니다`shifts`. 예를 들면 `/shifts/SHFT_12345678-1234-1234-1234-1234567890ab`와 같습니다.
머리글	WfiRequestHeader	머리글
몸	ShiftsEntity	url 속성에서 일치 `{EntityType}` 해야 합니다. shift, swapShiftsChangeRequest, timeOffReason, openshift, openShiftChangeRequest, offerShiftRequests, timeOff, timeOffRequest 중 하나를 사용합니다. 예를 들면 `/shifts/SHFT_12345678-1234-1234-1234-1234567890ab`와 같습니다.

POST /teams/{teamsId}/read의 경우

속성	유형	설명
id	String	엔터티의 ID
메서드	String	항상 `GET`입니다.
url	String	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	머리글
몸	ShiftsEntity	항상 `null`입니다.

WfiRequestHeader

속성	유형	설명
X-MS-Transaction-ID	String	트랜잭션 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	String	엔터티의 ID
상태	String	작업 결과
몸	WfiResponseBody	WfiResponseBody

WfiResponseBody

속성	유형	설명
eTag	String	eTag
오류	WfiResponseError	오류에 대한 세부 정보
데이터	String	요청된 데이터(읽기 요청의 경우)

WfiResponseError

속성	유형	설명
코드	String	오류 코드
메시지	String	오류 메시지

다음을 통해 공유

Shifts와 인력 관리 시스템을 동기화하는 사용자 지정 통합 만들기

개요

이 문서에서 사용되는 용어

시작하기 전에

필수 구성 요소

통합 프로세스 숙지

1단계: 커넥터 만들기

1a단계: Shifts의 변경 내용을 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 시스템에서 이루어졌는지 여부를 식별할 어떻게 할까요? 있나요?

인력 통합 등록

인력 통합을 등록하고 "SwapRequest, OfferShiftRequest 및 TimeOffReason"을 포함하여 "eligibilityFilteringEnabledEntities"를 지정했지만 응답 본문에는 "eligibilityFilteringEnabledEntities" 목록이 표시되지 않습니다.

인력 통합을 등록하고 "supportEntities"를 추가했지만 400 잘못된 요청 응답과 "잘못된 페이로드: 요청된 값 'shift, ....'을 수신합니다. 찾을 수 없습니다." 메시지

인력 통합을 등록하고 /connect, /update 및 /read 엔드포인트를 구현했지만 웹후크가 작동하지 않습니다.

엔드포인트 참조

요청

ConnectRequest

WfiRequestContainer

WfiRequest

POST /teams/{teamId}/update의 경우

POST /teams/{teamsId}/read의 경우

WfiRequestHeader

응답

WfiResponseContainer

WfiResponse

WfiResponseBody

WfiResponseError

관련 문서

피드백

추가 리소스