配置与目录的扩展属性同步Configure synchronization with directory extension attributes

重要说明: Microsoft Graph 中 /beta 版本下的 API 是预览版,可能会发生变化。Important: APIs under the /beta version in Microsoft Graph are in preview and are subject to change. 不支持在生产应用程序中使用这些 API。Use of these APIs in production applications is not supported.

您可以自定义您的同步架构,以包括 Azure Active Directory (Azure AD) 目录扩展属性。You can customize your synchronization schema to include Azure Active Directory (Azure AD) directory extension attributes. 本文介绍如何使用目录扩展特性 (extension_9d98asdfl15980a_Nickname) 来填充 User.CommunityNickname 销售队伍中的值。This article describes how to use a directory extension attribute (extension_9d98asdfl15980a_Nickname) to populate the value of User.CommunityNickname in Salesforce. 在此方案中,您必须将设置为设置数从 Windows Server Active Directory 部署到 Azure AD 目录扩展属性的 Azure AD 连接。In this scenario, you have Azure AD Connect set up to provision a number of directory extension attributes from Windows Server Active Directory on-premises to Azure AD.

本文假定您已添加了支持同步到通过Azure 门户,确保您知道应用程序显示名称,租户的应用程序和 Microsoft Graph 具有一个授权令牌。This article assumes that you have already added an application that supports synchronization to your tenant through the Azure Portal, that you know the application display name, and that you have an authorization token for Microsoft Graph. 有关如何获取授权令牌的信息,请参阅获取访问令牌调用 Microsoft GraphFor information about how to get the authorization token, see Get access tokens to call Microsoft Graph.

按显示名称查找服务主体对象Find the service principal object by display name

下面的示例演示如何查找具有显示名称"销售队伍沙盒"的服务主体对象。The following example shows how to find a service principal object with the display name "Salesforce Sandbox".

GET https://graph.microsoft.com/beta/servicePrincipals?$select=id,appId,displayName&$filter=startswith(displayName, 'salesforce')
Authorization: Bearer {Token}
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals(id,appId,displayName)",
    "value": [
    {
        "id": "167e33e9-f80e-490e-b4d8-698d4a80fb3e",
        "appId": "cd3ed3de-93ee-400b-8b19-b61ef44a0f29",
        "displayName": "Salesforce"
    },
    {
        "id": "8cbbb70b-7290-42da-83ee-89fa3517a977",
        "appId": "b0f2e3b1-fe31-4658-b216-44dcaeabb63a",
        "displayName": "salesforce 1"
    },
    {
        "id": "60443998-8cf7-4e61-b05c-a53b658cb5e1",
        "appId": "79079396-c301-405d-900f-e2e0c2439a90",
        "displayName": "Salesforce Sandbox"
    }
    ]
}

{servicePrincipalId}60443998-8cf7-4e61-b05c-a53b658cb5e1The {servicePrincipalId} is 60443998-8cf7-4e61-b05c-a53b658cb5e1.

服务主体的上下文中的列表同步作业List synchronization jobs in the context of the service principal

下面的示例演示如何获取jobId,您需要使用。The following example shows you how to get the jobId that you need to work with. 通常,响应返回只有一个作业。Generally, the response returns only one job.

GET https://graph.microsoft.com/beta/servicePrincipals/60443998-8cf7-4e61-b05c-a53b658cb5e1/synchronization/jobs
Authorization: Bearer {Token}
{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#servicePrincipals('60443998-8cf7-4e61-b05c-a53b658cb5e1')/synchronization/jobs",
    "value": [
        {
            "id": "SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa",
            "templateId": "SfSandboxOutDelta",
            "schedule": {},
            "status": {}
    }
    ]
}

{jobId}SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aaThe {jobId} is SfSandboxOutDelta.e4bbf44533ea4eabb17027f3a92e92aa.

查找所需的目录扩展属性的名称Find the name of the directory extension attribute you need

您将需要扩展特性的完整名称。You'll need the full name of the extension attribute. 如果您不知道的完整名称 (它应类似于extension_9d98asdfl15980a_Nickname),请参阅 directory 扩展属性以及如何对其进行检查的以下信息:If you don't know the full name (which should look similar to extension_9d98asdfl15980a_Nickname), see the following information about directory extension attributes and how to inspect them:

获取同步架构Get the synchronization schema

下面的示例演示如何获取同步架构。The following example shows how to get the synchronization schema.

GET https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema
Authorization: Bearer {Token}

注意: 为了提高可读性,可能缩短了此处显示的响应对象。Note: The response object shown here might be shortened for readability. 将返回实际呼叫中的所有属性。All the properties will be returned in an actual call.

HTTP/1.1 200 OK

{
  "directories": [
        {
              "id": "66e4a8cc-1b7b-435e-95f8-f06cea133828",
              "name": "Azure Active Directory",
              "objects": [
                {
                    "attributes": [
                        {
                          "anchor": true,
                          "caseExact": false,
                          "defaultValue": null,
                          "metadata": [],
                          "multivalued": false,
                          "mutability": "ReadWrite",
                          "name": "objectId",
                          "required": false,
                          "referencedObjects": [],
                          "type": "String"
                        },
                        {
                          "anchor": false,
                          "caseExact": false,
                          "defaultValue": null,
                          "metadata": [],
                          "multivalued": false,
                          "mutability": "ReadWrite",
                          "name": "streetAddress",
                          "required": false,
                          "referencedObjects": [],
                          "type": "String"
                        }
                    ],
                    "name": "User"
                }
             ]
        },
        {
              "id": "8ffa6169-f354-4751-9b77-9c00765be92d",
              "name": "salesforce.com",
              "objects": []
        }
  ],
 "synchronizationRules": [
        {
          "editable": true,
          "id": "4c5ecfa1-a072-4460-b1c3-4adde3479854",
          "name": "USER_OUTBOUND_USER",
          "objectMappings": [
                {
                    "attributeMappings": [
                            {
                              "defaultValue": "True",
                              "exportMissingReferences": false,
                              "flowBehavior": "FlowWhenChanged",
                              "flowType": "Always",
                              "matchingPriority": 0,
                              "source": {
                                "expression": "Not([IsSoftDeleted])",
                                "name": "Not",
                                "parameters": [
                                  {
                                    "key": "source",
                                    "value": {
                                      "expression": "[IsSoftDeleted]",
                                      "name": "IsSoftDeleted",
                                      "parameters": [],
                                      "type": "Attribute"
                                    }
                                  }
                                ],
                                "type": "Function"
                              },
                              "targetAttributeName": "IsActive"
                            }
                     ],
                    "enabled": true,
                    "flowTypes": "Add, Update, Delete",
                    "name": "Synchronize Azure Active Directory Users to salesforce.com",
                    "scope": null,
                    "sourceObjectName": "User",
                    "targetObjectName": "User"
            }]
        }]
}

添加目录的扩展特性,和属性之间的映射定义Add a definition for the directory extension attribute, and a mapping between the attributes

使用纯文本编辑器 (如记事本 + +JSON 编辑器联机) 您选择的:Use a plain text editor of your choice (for example, Notepad++ or JSON Editor Online) to:

  1. 添加的属性定义extension_9d98asdfl15980a_Nickname属性。Add an attribute definition for the extension_9d98asdfl15980a_Nickname attribute.

    • 在目录下找到名称为"Azure Active Directory"、 目录和对象的数组中找到一个指定的用户Under directories, find the directory with the name "Azure Active Directory", and in the object's array, find the one named User.
    • 将新属性添加到列表中,指定的名称和类型,如下面的示例中所示。Add the new attribute to the list, specifying the name and type, as shown in the following example.
  2. 添加 extension_9d98asdfl15980a_Nickname 之间 CommunityNickname属性映射Add an attribute mapping between extension_9d98asdfl15980a_Nickname and CommunityNickname.

    • synchronizationRules,查找作为源目录,并为目标目录 Salesforce.com 指定 Azure AD 的规则 ("sourceDirectoryName": "Azure Active Directory", "targetDirectoryName": "salesforce.com")。Under synchronizationRules, find the rule that specifies Azure AD as source directory, and Salesforce.com as the target directory ("sourceDirectoryName": "Azure Active Directory", "targetDirectoryName": "salesforce.com").
    • 在规则objectMappings ,找到用户之间的映射 ("sourceObjectName": "User", "targetObjectName": "User")。In the objectMappings of the rule, find the mapping between users ("sourceObjectName": "User", "targetObjectName": "User").
    • objectMapping attributeMappings数组中,添加一个新项,如下面的示例中所示。In the attributeMappings array of the objectMapping, add a new entry, as shown in the following example.
    {
        "directories": [
            {
                "id": "66e4a8cc-1b7b-435e-95f8-f06cea133828",
                "name": "Azure Active Directory",
                "objects": [
                    {
                        "attributes": [
                                ,{
                                "name": "extension_9d98asdfl15980a_Nickname",
                                "type": "String"
                                }
                        ],
                        "name":"User"
                    }]
            }
        ],
        "synchronizationRules": [
            {
            "editable": true,
            "id": "4c5ecfa1-a072-4460-b1c3-4adde3479854",
            "metadata": [..],
            "name": "USER_OUTBOUND_USER",
            "objectMappings": [
                {
                    "attributeMappings": [
                    ,{
                        "source": {
                            "name": "extension_9d98asdfl15980a_Nickname",
                            "type": "Attribute"
                        },
                        "targetAttributeName": "CommunityNickname"
                        }
                ],
                "name": "Synchronize Azure Active Directory Users to salesforce.com",
                    "scope": null,
                    "sourceObjectName": "User",
                    "targetObjectName": "User"
                }
            ],
            "priority": 1,
            "sourceDirectoryName": "Azure Active Directory",
            "targetDirectoryName": "salesforce.com"
            },
        ]
    }
    

保存修改后的同步架构Save the modified synchronization schema

保存更新的同步架构时,请确保您包括整个架构,其中包括未修改的部件。When you save the updated synchronization schema, make sure that you include the entire schema, including the unmodified parts. 此请求将使用您提供一个替换现有的架构。This request will replace the existing schema with the one that you provide.

PUT https://graph.microsoft.com/beta/servicePrincipals/{servicePrincipalId}/synchronization/jobs/{jobId}/schema
Authorization: Bearer {Token}
{
    "directories": [],
    "synchronizationRules": []
}

HTTP/1.1 201 No Content

如果架构已成功保存下, 一步迭代的同步作业,则它将启动重新处理您 Azure AD 中的所有帐户和新的映射将应用于所有已设置的帐户。If the schema was saved successfully, on the next iteration of the synchronization job, it will start re-processing all the accounts in your Azure AD, and the new mappings will be applied to all provisioned accounts.