擴充 API 驅動布建以同步處理自訂屬性

發行項
03/05/2024

根據預設，API 驅動布建應用程式支援處理屬於標準 SCIM 核心使用者和企業用戶架構一部分的屬性。您的記錄系統可能有您想要包含在 API 驅動布建中的自訂屬性。本進階教學課程說明如何擴充 API 驅動的佈建應用程式，以處理其他自定義屬性。

注意

嘗試此進階案例之前，建議您先確認使用下列其中一個 API 用戶端 Graph Explorer、cURL 或 Postman，確認您的現成布建應用程式組態如預期般運作。

範例案例

您已設定 API 驅動佈建應用程式。您正在布建應用程式已成功取用屬於標準 SCIM 核心使用者和企業使用者架構的屬性，並在 Microsoft Entra ID 中布建使用者。您現在想要將兩個自定義屬性 HireDate ，以及 JobCode 從您的 HR 系統傳送至輸入布建 API 端點。您要將這兩個自訂屬性對應至 Microsoft Entra 屬性 employeeHireDate 與 jobTitle。

步驟 1 - 擴充布建應用程式架構

在此步驟中，我們會將不屬於標準 SCIM 架構的兩個屬性「HireDate」和「JobCode」新增至布建應用程式，並在布建數據流中使用它們。

以至少應用程式管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式企業應用程式]。>
開啟您的 API 驅動佈建應用程式。
開啟 [ 布建] 刀鋒視窗。
按兩下 [ 編輯布建] 按鈕。
展開 [ 對應] 區 段，然後按下屬性對應連結。
向下捲動 [屬性對應] 頁面。選取 [顯示進階選項]，然後按兩下 [API] 連結的 [編輯屬性] 清單。
向下捲動至 [編輯屬性清單] 頁面的結尾。
將下列兩個屬性新增至清單作為 SCIM 架構延伸模組。您可以使用自己的 SCIM 架構命名空間。
urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate
urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode
儲存變更

注意

如果您想要只將一些額外的屬性新增至布建應用程式，請使用 Microsoft Entra 系統管理中心來擴充架構。如果您想要新增更多自定義屬性（例如20個以上的屬性），建議您使用 UpdateSchema CSV2SCIM PowerShell腳本的模式，以自動化上述手動程式。

步驟 2 - 對應自訂屬性

現在讓我們將這些延伸模組新增至布建應用程式屬性對應。

按兩下 [屬性對應] 頁面上的 [新增對應] 連結。
將 urn:ietf:params:scim:schemas:extension:contoso:1.0:User:HireDate 屬性對應至 employeeHireDate。按一下 [確定]。
接下來，選取的現有對應 title ，然後按下它以編輯對應。
編輯屬性對應至將包含 urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode 做為 Microsoft Entra 屬性一部分的 jobTitle 運算式。
```
  Join("", [title], "(", [urn:ietf:params:scim:schemas:extension:contoso:1.0:User:JobCode], ")")
```
使用此表達式對應時，如果 title 是 “Tour Lead” 且 JobCode是 “TL-1001”，則 Microsoft Entra 屬性 jobTitle 會設定為 “Tour Lead （TL-1001）”。
儲存屬性對應。

步驟 3 - 使用自訂屬性上傳大量要求

開啟您的 API 用戶端（Graph Explorer / Postman / cURL）。
使用自訂屬性複製並貼上大量要求。
將大量要求傳送至布建 API 端點 URL。
經過一段時間之後，您可以檢查布建記錄，以確認屬性變更。
您也可以確認 Microsoft Entra 使用者設定檔中的變更。的值 Employee hire date 會反映您的租用戶時區。

附錄

使用自訂屬性的大量要求

大量要求包含上述步驟中所設定的自定義屬性。

要求本文

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
    "Operations": [
    {
        "method": "POST",
        "bulkId": "701984",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"],
            "externalId": "701984",
            "userName": "bjensen@example.com",
            "name": {
                "formatted": "Ms. Barbara J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Barbara",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Babs Jensen",
            "nickName": "Babs",
            "emails": [
            {
              "value": "bjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "234300 Universal City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91608",
              "country": "USA",
              "formatted": "100 Universal City Plaza\nHollywood, CA 91608 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5555",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Guide",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
                "employeeNumber": "701984",
                "costCenter": "4130",
                "organization": "Universal Studios",
                "division": "Theme Park",
                "department": "Tour Operations",
                "manager": {
                  "value": "89607",
                  "displayName": "John Smith"
                 }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2021-05-01T00:00:00-05:00",
                "JobCode": "TG-1001"
            }            
        }
    },
    {
        "method": "POST",
        "bulkId": "701985",
        "path": "/Users",
        "data": {
            "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User"],
            "externalId": "701985",
            "userName": "Kjensen@example.com",
            "name": {
                "formatted": "Ms. Kathy J Jensen, III",
                "familyName": "Jensen",
                "givenName": "Kathy",
                "middleName": "Jane",
                "honorificPrefix": "Ms.",
                "honorificSuffix": "III"
            },
            "displayName": "Kathy Jensen",
            "nickName": "Kathy",
            "emails": [
            {
              "value": "kjensen@example.com",
              "type": "work",
              "primary": true
            }
            ],
            "addresses": [
            {
              "type": "work",
              "streetAddress": "100 Oracle City Plaza",
              "locality": "Hollywood",
              "region": "CA",
              "postalCode": "91618",
              "country": "USA",
              "formatted": "100 Oracle City Plaza\nHollywood, CA 91618 USA",
              "primary": true
            }
            ],
            "phoneNumbers": [
            {
              "value": "555-555-5545",
              "type": "work"
            }
            ],
            "userType": "Employee",
            "title": "Tour Lead",
            "preferredLanguage": "en-US",
            "locale": "en-US",
            "timezone": "America/Los_Angeles",
            "active":true,
            "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
              "employeeNumber": "701984",
              "costCenter": "4130",
              "organization": "Universal Studios",
              "division": "Theme Park",
              "department": "Tour Operations",
              "manager": {
                "value": "701984",
                "displayName": "Barbara Jensen"
             }
            },
            "urn:ietf:params:scim:schemas:extension:contoso:1.0:User": {
                "HireDate": "2022-07-15T00:00:00-05:00",
                "JobCode": "TL-1003"
            }            
        }
    }
],
    "failOnErrors": null
}

共用方式為