使用 Web API 创建和更新实体关系

项目
03/04/2017

发布日期： 2017年1月

适用于： Dynamics 365 (online),Dynamics 365 (on-premises),Dynamics CRM 2016,Dynamics CRM Online

Web API 支持关系元数据的操作。自定义实体关系元数据中所描述的概念也适用于 Web API。

本主题内容

关系资格

创建一对多关系

创建多对多关系

更新关系

删除关系

关系资格

在创建实体关系之前，应当确认实体是否有资格参与关系。您可以使用下表列出的操作确定资格。这些操作对应于实体关系资格中所描述的组织服务消息。

目的	说明
CanBeReferenced Action	检查指定的实体是否可以在一对多关系中充当主要实体（一）。
CanBeReferencing Action	检查指定的实体是否可以在一对多关系中充当引用实体（多）。
CanManyToMany Action	检查实体是否可以参与多对多关系。
GetValidManyToMany Function	返回参与多对多关系的实体集。
GetValidReferencedEntities Function	返回在一对多关系中可以充当指定实体的有效主要实体（一）的实体集。
GetValidReferencingEntities Function	返回在一对多关系中可以充当指定实体的有效相关实体（多）的实体集。

创建一对多关系

创建一对多关系时，使用OneToManyRelationshipMetadata EntityType进行定义。此定义包括查找属性，使用LookupAttributeMetadata EntityType进行定义，还需要使用AssociatedMenuConfiguration ComplexType、CascadeConfiguration ComplexType、Label ComplexType和LocalizedLabel ComplexType的复杂属性。查找属性设置为OneToManyRelationshipMetadata对象的Lookup单一值导航属性，并同时使用深层插入创建。详细信息：在一个操作中创建相关实体和一对多关系

如果您要对一对多关系应用自定义导航属性名称，您可以设置ReferencingEntityNavigationPropertyName和ReferencedEntityNavigationPropertyName属性的值。

生成定义关系和查找属性所需的 JSON 后，POSTJSON 为RelationshipDefinitions实体集。必须包含 Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata 的 @odata.type 属性值，以明确正在创建的关系类型，因为创建多对多关系也是使用此相同的实体集。生成的属性的 URI 在响应中返回。

请求

POST cc_WebAPI_ServiceURI/RelationshipDefinitions HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "SchemaName": "new_contact_new_bankaccount",
 "@odata.type": "Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata",
 "AssociatedMenuConfiguration": {
  "Behavior": "UseCollectionName",
  "Group": "Details",
  "Label": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Bank Accounts",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Bank Accounts",
    "LanguageCode": 1033
   }
  },
  "Order": 10000
 },
 "CascadeConfiguration": {
  "Assign": "Cascade",
  "Delete": "Cascade",
  "Merge": "Cascade",
  "Reparent": "Cascade",
  "Share": "Cascade",
  "Unshare": "Cascade"
 },
 "ReferencedAttribute": "contactid",
 "ReferencedEntity": "contact",
 "ReferencingEntity": "new_bankaccount",
 "Lookup": {
  "AttributeType": "Lookup",
  "AttributeTypeName": {
   "Value": "LookupType"
  },
  "Description": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "The owner of the account",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "The owner of the account",
    "LanguageCode": 1033
   }
  },
  "DisplayName": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Account Owner",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Account Owner",
    "LanguageCode": 1033
   }
  },
  "RequiredLevel": {
   "Value": "ApplicationRequired",
   "CanBeChanged": true,
   "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
  },
  "SchemaName": "new_AccountOwner",
  "@odata.type": "Microsoft.Dynamics.CRM.LookupAttributeMetadata"
 }
}

响应

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/RelationshipDefinitions(d475020f-5d7c-e511-80d2-00155d2a68d2)

创建多对多关系

创建多对多关系时，必须使用ManyToManyRelationshipMetadata EntityType进行定义。此定义包含要创建的相交实体的名称以及在应用程序中如何使用AssociatedMenuConfiguration ComplexType、Label ComplexType和LocalizedLabel ComplexType显示关系。详细信息：多对多关系

如果您要对多对多关系应用自定义导航属性名称，您可以设置Entity1NavigationPropertyName和Entity2NavigationPropertyName属性的值。

生成定义关系所需的 JSON 后，POSTJSON 为RelationshipDefinitions实体集。必须包含 Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata 的 @odata.type 属性值，以明确正在创建的关系类型，因为创建一对多关系也是使用此相同的实体集。生成的属性的 URI 在响应中返回。

请求

POST cc_WebAPI_ServiceURI/RelationshipDefinitions HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

{
 "SchemaName": "new_accounts_campaigns",
 "@odata.type": "Microsoft.Dynamics.CRM.ManyToManyRelationshipMetadata",
 "Entity1AssociatedMenuConfiguration": {
  "Behavior": "UseLabel",
  "Group": "Details",
  "Label": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Account",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Account",
    "LanguageCode": 1033
   }
  },
  "Order": 10000
 },
 "Entity1LogicalName": "account",
 "Entity2AssociatedMenuConfiguration": {
  "Behavior": "UseLabel",
  "Group": "Details",
  "Label": {
   "@odata.type": "Microsoft.Dynamics.CRM.Label",
   "LocalizedLabels": [
    {
     "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
     "Label": "Campaign",
     "LanguageCode": 1033
    }
   ],
   "UserLocalizedLabel": {
    "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
    "Label": "Campaign",
    "LanguageCode": 1033
   }
  },
  "Order": 10000
 },
 "Entity2LogicalName": "campaign",
 "IntersectEntityName": "new_accounts_campaigns"
}

响应

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: cc_WebAPI_ServiceURI/RelationshipDefinitions(420245fa-c77c-e511-80d2-00155d2a68d2)

更新关系

正如更新实体中所讨论的，您使用 HTTP PUT 方法更新关系，将现有定义替换为您要应用的更改。您无法像业务数据实体一样，使用 HTTP PATCH 方法编辑单个属性。正如实体和属性一样，应包含一个 MSCRM.MergeLabels 标头，其值设置为 true，以免覆盖更新中不包含的本地化标签，且您必须在它们在系统中生效之前发布自定义项。

删除关系

要使用 Web API 删除关系，请使用 HTTP DELETE 方法与此关系的 URI。

另请参阅

自定义实体关系元数据
 使用具有 Dynamics 365 元数据的 Web API
使用 Web API 查询元数据
 按名称或 MetadataId 检索元数据
 使用 Web API 创建更新实体定义

Microsoft Dynamics 365

使用 Web API 创建和更新实体关系

本主题内容

关系资格

创建一对多关系

创建多对多关系

更新关系

删除关系

另请参阅

其他资源