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

發行項
08/09/2024

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

注意

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

範例案例

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

步驟 1 - 擴充佈建應用程式結構描述

在此步驟中，我們會將不屬於標準 SCIM 結構描述的兩個屬性「HireDate」和「JobCode」新增至佈建應用程式，並在佈建資料流程中使用它們。

以至少應用程式系統管理員的身分登入 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 個以上的屬性)，建議您使用 CSV2SCIM PowerShell 指令碼 UpdateSchema 的模式，自動執行上述手動流程。

步驟 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 做為 jobTitle Microsoft Entra 屬性的一部分。
```
  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 / 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
}

共用方式為