使用 Web API 查詢中繼資料

發行項
03/04/2017

發行︰ 2017年1月

適用於： Dynamics 365 (online)、Dynamics 365 (on-premises)、Dynamics CRM 2016、Dynamics CRM Online

由於 Microsoft Dynamics 365 是中繼資料導向的應用程式，因此開發人員可能需要在執行階段查詢系統中繼資料，以符合組織設定的方式。此功能可透過使用 Web API 以及使用組織服務提供，藉由使用 RetrieveMetadataChangesRequest 和 Microsoft.Xrm.Sdk.Metadata.Query 命名空間的類別。 Web API 允許查詢中繼資料，但未提供偵測自某一時間點的中繼資料變更的功能。

本主題內容

查詢 EntityMetadata 實體類型

在 $filter 作業中使用列舉類型

在 $filter 作業中使用複雜類型

查詢 EntityMetadata 屬性

擷取屬性

查詢關聯中繼資料

查詢全域選項組

查詢 EntityMetadata 實體類型

您將使用使用 Web API 查詢資料中所述的相同技術，當您查詢 EntityMetadata 時，並搭配部分變化。使用 EntityDefinitions 實體設定路徑來擷取有關 EntityMetadata EntityType 的資訊。EntityMetadata 實體包含大量資料，因此您應小心只擷取您需要的資料。下列範例顯示僅針對 DisplayNameIsKnowledgeManagementEnabled 傳回的資料，以及 Account 實體的中繼資料的 EntitySetName 屬性。MetadataId 屬性值一律傳回。

要求

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=DisplayName,IsKnowledgeManagementEnabled,EntitySetName&$filter=SchemaName eq 'Account' HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

回覆

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(DisplayName,IsKnowledgeManagementEnabled,EntitySetName)",
 "value": [
  {
   "DisplayName": {
    "LocalizedLabels": [
     {
      "Label": "Account",
      "LanguageCode": 1033,
      "IsManaged": true,
      "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",
      "HasChanged": null
     }
    ],
    "UserLocalizedLabel": {
     "Label": "Account",
     "LanguageCode": 1033,
     "IsManaged": true,
     "MetadataId": "2a4901bf-2241-db11-898a-0007e9e17ebd",
     "HasChanged": null
    }
   },
   "IsKnowledgeManagementEnabled": false,
   "EntitySetName": "accounts",
   "MetadataId": "70816501-edb9-4740-a16c-6a5efbc05d84"
  }
 ]
}

您可以使用任何 EntityMetadata 屬性搭配 $select 系統查詢選項，也可以在任何使用基本或列舉值的屬性上使用 $filter。

查詢中將傳回的中繼資料實體數目並無限制。沒有分頁。所有符合的資源將會在第一個回覆中傳回。

在 $filter 作業中使用列舉類型

當您需要根據使用列舉的屬性值篩選中繼資料實體時，您必須在字串值前面包括列舉的命名空間。列舉類型僅做為中繼資料實體和複雜類型中的屬性值使用。例如，如果您需要根據 OwnershipType 屬性篩選實體，其使用 OwnershipTypes EnumType，您可以使用下列 $filter 僅傳回是 UserOwned 的實體。

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=OwnershipType eq Microsoft.Dynamics.CRM.OwnershipTypes'UserOwned'

在 $filter 作業中使用複雜類型

當您需要根據使用複雜類型的屬性值篩選中繼資料實體時，您必須包括基礎基本類型的路徑。複雜類型僅做為中繼資料實體中的屬性值使用。例如，如果您需要根據 CanCreateAttributes 屬性篩選實體，其使用 BooleanManagedProperty ComplexType，您可以使用下列 $filter 僅傳回 Value 是 true 的實體。

GET cc_WebAPI_ServiceURI/EntityDefinitions?$select=LogicalName&$filter=CanCreateAttributes/Value eq true

此模式可搭配 BooleanManagedProperty ComplexType 運作，因為要檢查的基本值深度僅一層。不過，這在 Label ComplexType 的屬性上無法運作。

查詢 EntityMetadata 屬性

您可以在實體內容中查詢實體屬性，藉由展開 Attributes 集合值導覽屬性，但是這只會包含 AttributeMetadata EntityType 中所有屬性共用的通用屬性。例如，下列查詢將傳回實體的 LogicalName，以及所有展開的 Attributes，其 AttributeType 值相當於 AttributeTypeCode EnumType 值 Picklist。

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)?$select=LogicalName&$expand=Attributes($select=LogicalName;$filter=AttributeType eq Microsoft.Dynamics.CRM.AttributeTypeCode'Picklist')

但是，您無法在此查詢的 $select 篩選內，包含 PicklistAttributeMetadata EntityType 屬性擁有的 OptionSet 或 GlobalOptionSet 集合值導覽屬性。

若要擷取特定類型屬性的屬性，您必須將 Attributes 集合值導覽屬性轉換成您要的類型。下列查詢只會傳回 PicklistAttributeMetadata 屬性，並包含 LogicalName 以及展開 OptionSet 和 GlobalOptionSet 集合值導覽屬性。

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet,GlobalOptionSet

注意

雖然 OptionSet 和 GlobalOptionSet 集合值導覽屬性是在 EnumAttributeMetadata EntityType 中定義，但是您無法將屬性轉換成此類型。這表示，若您想要篩選同樣繼承這些屬性的其他類型 (請參閱Entity types that inherit from activitypointer)，則必須執行不同的查詢來篩選每一種類型。

另一個類似的範例是存取 MoneyAttributeMetadata EntityType 和 DecimalAttributeMetadata EntityType 屬性中提供的 Precision 屬性。若要存取此屬性，您必須將屬性集合轉換成 MoneyAttributeMetadata 或 DecimalAttributeMetadata。此處顯示轉換成 MoneyAttributeMetadata 的範例。

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.MoneyAttributeMetadata?$select=LogicalName,Precision

依必要層級篩選

AttributeMetadata EntityTypeRequiredLevel 屬性使用特殊的 AttributeRequiredLevelManagedProperty ComplexType，其中 Value 屬性是 AttributeRequiredLevel EnumType。在此情況下，您必須結合在 $filter 作業中使用複雜類型和在 $filter 作業中使用列舉類型中找到的模式，並依此唯一屬性進行篩選。下列查詢將在帳戶實體中篩選這些屬性 (為 ApplicationRequired)。

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes?$select=SchemaName&$filter=RequiredLevel/Value eq Microsoft.Dynamics.CRM.AttributeRequiredLevel'ApplicationRequired'

擷取屬性

當您知道 EntityMetadata 與 AttributeMetadata 的 MetadataId 時，可以使用類似下列的查詢擷取個別屬性和存取屬性值。此查詢會擷取屬性的 LogicalName 屬性，以及展開 OptionSet 集合值導覽屬性。請注意，您必須將屬性轉換為 Microsoft.Dynamics.CRM.PicklistAttributeMetadata，才能存取 OptionSet 集合值導覽屬性。

要求

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata?$select=LogicalName&$expand=OptionSet HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

回覆

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes/Microsoft.Dynamics.CRM.PicklistAttributeMetadata(LogicalName,OptionSet)/$entity",
 "LogicalName": "preferredappointmentdaycode",
 "MetadataId": "5967e7cc-afbb-4c10-bf7e-e7ef430c52be",
 "OptionSet@odata.context": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet/$entity",
 "OptionSet": {
  "Options": [
   {
    "Value": 0,
    "Label": {
     "LocalizedLabels": [
      {
       "Label": "Sunday",
       "LanguageCode": 1033,
       "IsManaged": true,
       "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",
       "HasChanged": null
      }
     ],
     "UserLocalizedLabel": {
      "Label": "Sunday",
      "LanguageCode": 1033,
      "IsManaged": true,
      "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",
      "HasChanged": null
     }
    },
    "Description": {
     "LocalizedLabels": [],
     "UserLocalizedLabel": null
    },
    "Color": null,
    "IsManaged": true,
    "MetadataId": null,
    "HasChanged": null
   }
Additional options removed for brevity
  ],
  "Description": {
   "LocalizedLabels": [
    {
     "Label": "Day of the week that the account prefers for scheduling service activities.",
     "LanguageCode": 1033,
     "IsManaged": true,
     "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",
     "HasChanged": null
    }
   ],
   "UserLocalizedLabel": {
    "Label": "Day of the week that the account prefers for scheduling service activities.",
    "LanguageCode": 1033,
    "IsManaged": true,
    "MetadataId": "1b67144d-ece0-4e83-a38b-b4d48e3f35d5",
    "HasChanged": null
   }
  },
  "DisplayName": {
   "LocalizedLabels": [
    {
     "Label": "Preferred Day",
     "LanguageCode": 1033,
     "IsManaged": true,
     "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",
     "HasChanged": null
    }
   ],
   "UserLocalizedLabel": {
    "Label": "Preferred Day",
    "LanguageCode": 1033,
    "IsManaged": true,
    "MetadataId": "ebb7e979-f9e3-40cd-a86d-50b479b1c5a4",
    "HasChanged": null
   }
  },
  "IsCustomOptionSet": false,
  "IsGlobal": false,
  "IsManaged": true,
  "IsCustomizable": {
   "Value": true,
   "CanBeChanged": false,
   "ManagedPropertyLogicalName": "iscustomizable"
  },
  "Name": "account_preferredappointmentdaycode",
  "OptionSetType": "Picklist",
  "IntroducedVersion": null,
  "MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735",
  "HasChanged": null
 }
}

如果您不需要屬性的任何屬性，而且只要集合值導覽屬性的值 (例如 OptionsSet)，您可以將它包括在 URL 中，並使用 $select 系統查詢選項限制屬性，讓查詢更有效率。在下列範例中，只包含 OptionSet 的 Options 屬性。

要求

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet?$select=Options HTTP/1.1
Accept: application/json
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0

回覆

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
 "@odata.context": "cc_WebAPI_ServiceURI/$metadata#EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/Attributes(5967e7cc-afbb-4c10-bf7e-e7ef430c52be)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet(Options)/$entity",
 "Options": [{
   "Value": 0,
   "Label": {
    "LocalizedLabels": [{
     "Label": "Sunday",
     "LanguageCode": 1033,
     "IsManaged": true,
     "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",
     "HasChanged": null
    }],
    "UserLocalizedLabel": {
     "Label": "Sunday",
     "LanguageCode": 1033,
     "IsManaged": true,
     "MetadataId": "21d6a218-2341-db11-898a-0007e9e17ebd",
     "HasChanged": null
    }
   },
   "Description": {
    "LocalizedLabels": [],
    "UserLocalizedLabel": null
   },
   "Color": null,
   "IsManaged": true,
   "MetadataId": null,
   "HasChanged": null
  }
Additional options removed for brevity
 ],
 "MetadataId": "53f9933c-18a0-40a6-b4a5-b9610a101735"
}

查詢關聯中繼資料

您可以在特定實體的內容中擷取關聯中繼資料，就像您可以查詢屬性一樣。ManyToManyRelationships、ManyToOneRelationships 和 OneToManyRelationships 集合值導覽屬性可供查詢，就像 Attributes 集合值導覽屬性一樣。其他資訊：查詢 EntityMetadata 屬性

不過，實體關聯也可以使用 RelationshipDefinitions 實體集查詢。您可以使用類似下列的查詢取得每個關聯的 SchemaName 屬性。

GET cc_WebAPI_ServiceURI/RelationshipDefinitions?$select=SchemaName

查詢此實體集時可用的屬性限於 RelationshipMetadataBase EntityType 中的屬性。若要從繼承自 RelationshipMetadataBase 的實體類型存取屬性，您需要在查詢中包含轉換，類似下面這個查詢，以便只傳回 OneToManyRelationshipMetadata EntityType。

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName

由於傳回的實體類型為 OneToManyRelationshipMetadata，因此您可以篩選屬性 (像是 ReferencedEntity) 來建構查詢，只傳回特定實體的一對多實體關聯，例如下列查詢中所顯示的帳戶實體：

GET cc_WebAPI_ServiceURI/RelationshipDefinitions/Microsoft.Dynamics.CRM.OneToManyRelationshipMetadata?$select=SchemaName&$filter=ReferencedEntity eq 'account'

該查詢基本上會傳回與下列查詢相同的結果，且經過篩選，因為它包含在帳戶實體的 EntityMetadataOneToManyRelationships 集合值導覽屬性中。差別在於前一個查詢不需要知道帳戶實體的 MetadataId。

GET cc_WebAPI_ServiceURI/EntityDefinitions(70816501-edb9-4740-a16c-6a5efbc05d84)/OneToManyRelationships?$select=SchemaName

查詢全域選項組

您可以使用 GlobalOptionSetDefinitions 實體設定路徑來擷取全域選項組的資訊，但此路徑不支援使用 $filter 系統查詢選項。因此，除非您知道特定全域選項組的 MetadataId，否則只能全部擷取。您也可以針對使用它的任何屬性，從 GlobalOptionSet 單一值導覽屬性內存取全域選項組的定義。這適用於所有Entity types that inherit from activitypointer。其他資訊：擷取屬性

另請參閱

使用 Web API 搭配 Dynamics 365 中繼資料
 依名稱或 MetadataId 擷取中繼資料
 使用 Web API 建立和更新實體定義
 使用 Web API 建立和更新實體關聯

Microsoft Dynamics 365

共用方式為

使用 Web API 查詢中繼資料

本主題內容

查詢 EntityMetadata 實體類型

在 $filter 作業中使用列舉類型

在 $filter 作業中使用複雜類型

查詢 EntityMetadata 屬性

依必要層級篩選

擷取屬性

查詢關聯中繼資料

查詢全域選項組

另請參閱

其他資源