Web API 類型和作業

 

發行︰ 2017年1月

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

若要使用 Web API，您需要找出哪些項目可供您使用的資訊。 服務透過您可存取的服務和中繼資料文件自我描述。 本主題將介紹重要的概念，並描述如何尋找需要的資訊，使用服務和中繼資料文件產生的文件，以及系統實體類型、功能和動作的文件。

本主題內容

辭彙

服務文件

實體類型

屬性

導覽屬性

動作

Functions

複雜類型

列舉類型

辭彙

Web API 是使用 OData v4 標準實作，其使用一套特定的詞彙，您必須熟悉。實體資料模型 (EDM) 是抽象資料模型，用來描述 OData 服務公開的資料。 下表精選 OData 4.0 版第 1 部分：通訊協定加上 Errata 02 中定義的詞彙清單，您應了解。

術語	定義
實體類型	含索引鍵的具名結構化類型。 它們定義實體的具名屬性和關聯。 實體類型可藉由單一繼承衍生自其他實體類型。
實體	實體類型的執行個體 (例如 account、opportunity)。
實體集	具名實體集合 (例如 accounts 是包含 account 實體的實體集)。 實體的索引鍵在實體集中用來唯一識別實體
複雜類型	無索引鍵具名結構化類型，由一組屬性組成。 複雜類型通常做為模型實體中的屬性值使用，或是做為作業的參數或傳回值。
列舉類型或列舉類型	具名基本值類型，其值是具名的常數，具有基礎整數值。
Functions	沒有副作用且支援進一步撰寫的作業，例如使用其他篩選作業、功能或動作
動作	允許副作用的作業，例如資料修改，且無法進一步撰寫以避免非決定的行為

服務文件

您可參考兩份服務文件以進一步了解 Web API。

服務文件

下列查詢 (輸入您瀏覽器的網址欄位中) 會傳回服務文件，可供您組織使用的所有實體集的完整清單。 請注意，[組織 URI] 代表組織的 URL。

[組織 URI]/api/data/v8.2

傳回的實體集為 JSON 陣列形式。 陣列中的每個項目都有三個屬性，如表中所列。

屬性	描述
name	此為實體集的名稱。 此資料來自實體的 EntityMetadata EntityTypeEntitySetName 屬性。
kind	僅針對 Web API 列出實體集。
url	此值與 name 屬性相同，代表為實體擷取資料的資源路徑的一部分。

此資訊可使用 GET 要求擷取，方便使用服務取得所有可用實體集的清單。

CSDL 中繼資料文件

對下列 URL 的 GET 要求會傳回相當大 (超過 3.5 MB) 的通用結構描述定義語言 (CSDL) 文件，或中繼資料文件，描述服務所公開的資料和作業。

[組織 URI]/api/data/v8.2/$metadata

此文件可做為資料來源用來產生類別，為服務提供強型別物件。 但是，如果您不使用產生的類別，建議您改為檢閱自此資訊產生的文件。Web API Reference 主要使用來自此文件的資訊，此文件取自非自訂系統。

您可以深入了解此文件，於 OData 4.0 版第 3 部分：通用結構描述定義語言 (CSDL) 加上 Errata 02。

提示

在閱讀本主題其餘內容之前，請先為您的組織下載 CSDL，並了解所述的類型、功能和動作如何包含在 CSDL 及支援文件中。

實體類型

Web API EntityType Reference 列出每一個透過儲存商務資料的 Web API 公開的系統實體類型。 實體類型是具有索引鍵的具名結構化類型。 它定義實體的具名屬性和關聯。 實體類型可藉由單一繼承衍生自其他實體類型。Web API Metadata EntityType Reference 列出每一個用來管理系統中繼資料的實體類型。 兩者都是實體類型，但是使用的方式不同。 如需使用模型實體的詳細資訊，請參閱使用 Web API 搭配 Dynamics 365 中繼資料。 每個實體類型都包含在 CSDL 的 EntityType 元素中。 以下是來自 CSDL 的 account EntityType 定義，當中的屬性和導覽屬性已移除。

<EntityType Name="account" BaseType="mscrm.crmbaseentity">
  <Key>
    <PropertyRef Name="accountid" />
  </Key>
  <!--Properties and navigation properties removed for brevity-->
  <Annotation Term="Org.OData.Core.V1.Description" String="Business that represents a customer or potential customer. The company that is billed in business transactions." />
</EntityType>

SDK 文件中的每個 EntityType 參考頁都使用來自 CSDL 或中繼資料的資訊，在可用的時候顯示下列資訊。

資訊	描述
描述	實體的描述。 EntityMetadata EntityType Description 屬性資訊包含在 EntityType 元素中，使用 Annotation 元素搭配 Org.OData.Core.V1.Description 的 Term 屬性值。
集合 URL	存取每個類型集合的 URL。 EntityMetadata EntityTypeEntitySetName 屬性資訊是使用 CSDL EntityContainer 元素包含。 每個 EntitySet 元素的 Name 屬性負責控制透過 URL 存取資料的方式。
基底類型	這是實體類型所繼承的實體類型。 EntityType 元素的 BaseType 屬性包含實體類型的名稱。 此名稱前面會加上 Microsoft.Dynamics.CRM 命名空間的別名做為首碼：mscrm。其他資訊：類型繼承
顯示名稱	此資訊不在 CSDL 中，是從 EntityMetadata EntityTypeDisplayName 屬性擷取。
主索引鍵	屬性值，包含參考實體執行個體的唯一識別碼。 EntityMetadata EntityTypePrimaryIdAttribute 屬性值包含在 EntityTypeKey 元素中。 每個實體只有一個主索引鍵。 此處未列出其他索引鍵。其他資訊：其他索引鍵
主要屬性	許多實體都需要設定主要屬性值，以便將它包含在內。 此資訊不在 CSDL 中，是從中繼資料 EntityMetadata EntityTypePrimaryNameAttribute 屬性擷取。
屬性	請參閱屬性。
單一值導覽屬性	請參閱單一值導覽屬性。
集合值導覽屬性	請參閱集合值導覽屬性。
繫結至實體類型的作業	當作業繫結至特定實體類型時，就會列出以便使用。
使用實體類型的作業	此清單會顯示可使用實體類型的所有作業。 這是藉由收集在參數中參考目前類型或做為傳回值的所有作業的參考所衍生。
繼承自實體類型的實體類型	此清單包含直接繼承自實體類型的任何實體類型。 如需詳細資訊，請參閱類型繼承。

變更實體集的名稱

根據預設，實體集名稱與 EntityMetadata EntityType LogicalCollectionName (EntityMetadataLogicalCollectionName) 屬性值相符。 如果您想要使用不同的實體集名稱定址自訂實體，可以將 EntityMetadata EntityTypeEntitySetName (EntityMetadata.EntitySetName) 屬性值更新為使用不同名稱。

其他索引鍵

雖然 Microsoft Dynamics 365 允許建立其他索引鍵，但是 Microsoft Dynamics 365 SDK 文件中只會找到主索引鍵。

系統實體都不會定義其他索引鍵。 如果您為實體定義其他索引鍵，它們會包含在 CSDL EntityType 元素中做為 Annotation，如下：

<Annotation Term="OData.Community.Keys.V1.AlternateKeys">
  <Collection>
    <Record Type="OData.Community.Keys.V1.AlternateKey">
      <PropertyValue Property="Key">
        <Collection>
          <Record Type="OData.Community.Keys.V1.PropertyRef">
            <PropertyValue Property="Alias" String="key name" />
            <PropertyValue Property="Name" PropertyPath="key name" />
          </Record>
        </Collection>
      </PropertyValue>
    </Record>
  </Collection>
</Annotation>

有關其他索引鍵的資訊也可以透過使用 Web API 的 EntityMetadata EntityTypeKeys 集合值導覽屬性從中繼資料擷取，或透過使用組織服務的 EntityMetadata.Keys 屬性。

類型繼承

繼承允許共用通用屬性以及將實體類型分類為群組。 Web API 中的所有實體類型都繼承自下列兩種實體類型。 所有商務實體類型都繼承自 crmbaseentity EntityType，而所有模型實體都繼承自 crmmodelbaseentity EntityType。

基底實體	描述
crmbaseentity EntityType	所有商務實體都繼承自此實體。 它沒有屬性。 它只當做抽象基底實體。
activitypointer EntityType	所有活動實體都繼承自此實體。 它為活動實體定義一組通用的屬性集和導覽屬性。
principal EntityType	systemuser EntityType 和 team EntityType 會從此實體繼承通用的 ownerid 屬性。
crmmodelbaseentity EntityType	只有 MetadataBase EntityType 直接自此實體繼承。 它沒有屬性。 它只當做抽象基底實體。
MetadataBase EntityType	所有模型實體都繼承自此實體。 它為所有模型實體提供 MetadataId 和 HasChanged 屬性。
AttributeMetadata EntityType	代表繼承自此實體的不同類型屬性的所有模型實體。
EnumAttributeMetadata EntityType	這些模型實體代表的屬性包含一組繼承自此實體的選項。
OptionSetMetadataBase EntityType	此模型實體類型提供一組通用的屬性，可供繼承自它的 BooleanOptionSetMetadata EntityType 和 OptionSetMetadata EntityType 模型實體類型使用。
RelationshipMetadataBase EntityType	此實體類型提供一組通用的屬性，可供繼承自它的 ManyToManyRelationshipMetadata EntityType 和 OneToManyRelationshipMetadata EntityType 模型實體類型使用。

屬性

每個實體類型都可能有回應屬性的宣告屬性。 在 Web API EntityType Reference 和 Web API Metadata EntityType Reference 內容中，繼承自基底實體類型的屬性會在每個實體類型的宣告屬性清單內結合。 繼承會在每個屬性的描述中提出。

在 CSDL EntityType 元素中，每個屬性會包含在 Property 元素中，並且具有 Name 屬性值，用於回應您將在程式碼中設定的屬性。Type 屬性值指定屬性的資料類型。 商務實體類型的屬性通常使用 OData 基本值類型。

下列範例是在 CSDL 中定義的 account EntityTypename 屬性。

<Property Name="name" Type="Edm.String" Unicode="false">
  <Annotation Term="Org.OData.Core.V1.Description" String="Type the company or business name." />
</Property>

屬性的描述會在 Annotation 元素中提供，且包含 Org.OData.Core.V1.Description 的 Term 屬性內容。 此描述取自 AttributeMetadata EntityTypeDescription 屬性值。 並非所有屬性都有描述。

每個屬性都可計算。 這表示，值可由系統設定。 這是在 Annotation 元素中指定，且 Term 屬性值為 Org.OData.Core.V1.Computed。

每個屬性也都可以設定是否更新的限制。 這是在 Annotation 元素中定義，且 Term 屬性值為 Org.OData.Core.V1.Permissions。 唯一的選項組是 Org.OData.Core.V1.PermissionType/Read，表示屬性是唯讀的。

基本值類型

OData 支援多種資料類型，但是 Microsoft Dynamics 365 不會使用全部的資料類型。 下表描述 Dynamics 365 組織服務類型如何對應至 OData 基本值類型。

組織服務類型	Web API 類型	描述
BigInt	Edm.Int64	帶正負號的 64 位元整數
Boolean	Edm.Boolean	二進位值邏輯
CalendarRules	單一值導覽屬性	calendarrule EntityType 的特定單一值導覽屬性。
客戶	單一值導覽屬性	具有此類型屬性的實體客戶可能是單一值導覽屬性，設定為 account 或 contact 實體類型，使用個別的單一值導覽屬性。 設定任一個別單一值集合屬性後，另一個就會清除。
DateTime	Edm.DateTimeOffset	具有時區差距的日期和時間，無閏秒 OData 中沒有 DateTime 類型。
Decimal	Edm.Decimal	有固定有效位數及範圍的數值
Double	Edm.Double	IEEE 754 binary64 浮點數 (15-17 十進位數)
EntityName	Edm.String	UTF-8 字元順序
圖像	Edm.Binary	二進位資料
整數	Edm.Int32	帶正負號的 32 位元整數
查詢	單一值導覽屬性	特定實體的參考
ManagedProperty	不適用	僅供內部使用。
備忘	Edm.String	UTF-8 字元順序
金額	Edm.Decimal	有固定有效位數及範圍的數值
負責人	單一值導覽屬性	principal EntityType 的參考。systemuser 和 team 實體類型的 ownerid 屬性都是繼承自 prinicipal 實體類型。
當事人清單	activityparty 實體類型的集合值導覽屬性。	activitypartyparticipationtypemask 屬性包含代表參與者角色的值。 如需詳細資訊，請參閱活動當事人類型。
挑選清單	Edm.Int32	帶正負號的 32 位元整數
狀態	Edm.Int32	帶正負號的 32 位元整數
狀態	Edm.Int32	帶正負號的 32 位元整數
String	Edm.String	UTF-8 字元順序
Uniqueidentifier	Edm.Guid	16 位元組 (128 位元) 唯一識別碼

查詢屬性

對於大部分的單一值導覽屬性，您會發現有計算的唯讀屬性，它使用下列命名慣例：_<name>_value，其中 <name> 與單一值導覽屬性的名稱相符。 此模式的例外狀況是實體的查詢屬性能夠接受多種類型的實體參考時。 通用範例是如何將 incident 實體 customerid 屬性設定為本身是 contact 或 account 實體的參考。 在 incident EntityTypeSingle-valued navigation properties 中，您會發現 customerid_account 和 customerid_contact 是個別的單一值導覽屬性，可反映與商機相關聯的客戶。 若您設定其中一個單一值導覽屬性，另一個將會設定為 null，因為兩者都繫結至 customerid 屬性。 在 incident EntityTypeProperties 中，您會找到 _customerid_value 查詢屬性，當中包含的值與擁有值得任一個單一值導覽屬性的值相同。

一般而言，您應避免使用查詢屬性，而改用對應的單一值導覽屬性。 這些屬性已包含在內，因為它們對於某些整合案例很有用。 這些屬性是唯讀的並經過計算，因為它們只會反映使用對應的單一值導覽屬性套用的變更。

您在查詢中包含查詢屬性時，可以要求包含註解，以提供有關為基礎屬性設定的資料的額外資訊，因為這些屬性不是由單一值導覽屬性表示。其他資訊：擷取有關查詢屬性的資料

導覽屬性

在 OData 中，導覽屬性可讓您存取與目前實體相關的資料。 當您擷取實體時，可以選擇展開導覽屬性以包含相關資料。 導覽屬性有兩種：單一值和集合值。

單一值導覽屬性

這些屬性對應查詢屬性，支援多對一關聯並允許設定另一個實體的參考。 在 CSDL EntityType 元素中，這些會定義為 NavigationProperty 元素，且 Type 屬性設為單一類型。 下列範例是 CSDL 中的 account EntityTypecreatedby 單一值導覽屬性：

<NavigationProperty Name="createdby" Type="mscrm.systemuser" Nullable="false" Partner="lk_accountbase_createdby">
 <ReferentialConstraint Property="_createdby_value" ReferencedProperty="systemuserid" />
</NavigationProperty>

代表單一值導覽屬性的每一個導覽屬性都有對應的集合值導覽屬性，以 Partner 屬性值表示。 每個單一值導覽屬性也都有 ReferentialConstraint 元素，其中 Property 屬性值代表計算的唯讀查詢屬性，可用來擷取相關實體的對應 GUID 值。其他資訊：查詢屬性

集合值導覽屬性

這些屬性對應至一對多或多對多關聯。 在 CSDL EntityType 元素中，這些會定義為 NavigationProperty 元素，且 Type 屬性設為類型集合。 以下代表 account EntityTypeAccount_Tasks 集合值導覽屬性，代表一對多關聯：

<NavigationProperty Name="Account_Tasks" Type="Collection(mscrm.task)" Partner="regardingobjectid_account_task" />

集合值導覽屬性代表多對多關聯，導覽屬性的名稱和合作夥伴的名稱會相同。 以下代表 account EntityTypeaccountleads_association 集合值導覽屬性，代表多對多關聯：

<NavigationProperty Name="accountleads_association" Type="Collection(mscrm.lead)" Partner="accountleads_association" />

使用 Web API 時，一對多和多對多關聯之間的差異並不重要。 在實體之間建立關聯的方式均相同，不論關聯的類型為何。 雖然多對多關聯在背後仍然使用交集實體，但只有少數特殊系統交集實體會包含在 Web API EntityType Reference內。 例如，campaignactivityitem EntityType 在技術上是交集實體，但是它會包含在內，因為它擁有的屬性比一般交集實體多。

一般交集實體只要有四個基本屬性，就能維護多對多關聯。 當您在實體之間建立自訂多對多關聯時，將會建立一般交集實體以支援關聯。 因為您應使用導覽屬性執行包含多對多關聯的作業，所以一般交集實體雖然並未記載，但仍可透過 Web API 使用。 這些交集實體類型可透過使用下列命名慣例的實體集名稱存取：<交集實體邏輯名稱>+'collection'。 例如，您可以使用 [組織 URI]/api/data/v8.2/contactleadscollection 從 contactleads 交集實體類型擷取資訊。 只有在您想要套用變更追蹤時，才使用這些一般交集實體。

動作

動作是允許副作用的作業，例如資料修改，且無法進一步撰寫以避免非決定的行為。

Web API Action Reference主題列出每一項可用的系統動作。其他資訊：使用 Web API 動作。

Functions

功能是沒有副作用且支援進一步撰寫的作業，例如使用其他篩選作業、功能或動作

Web API 中定義的功能有兩種類型：

• Web API Function Reference列出每一項可用的系統功能。

• Web API Query Function Reference主題列出在查詢中做為準則使用的功能。

其他資訊：使用 Web API 功能

複雜類型

複雜類型是無索引鍵具名結構化類型，由一組屬性組成。 複雜類型通常做為模型實體中的屬性值使用，或是做為作業的參數或傳回值。

Web API ComplexType Reference列出所有系統複雜類型。複雜類型是無索引鍵具名結構化類型，由一組屬性組成。 它們通常做為模型實體中的屬性值使用，或是做為作業的參數或傳回值。 以下是來自 CSDL 的 WhoAmIResponse ComplexType。

<ComplexType Name="WhoAmIResponse">
  <Property Name="BusinessUnitId" Type="Edm.Guid" Nullable="false" />
  <Property Name="UserId" Type="Edm.Guid" Nullable="false" />
  <Property Name="OrganizationId" Type="Edm.Guid" Nullable="false" />
</ComplexType>

列舉類型

列舉類型 (或稱 EnumTypes) 是具名基本值類型，其值是具名的常數，具有基礎整數值。

Web API EnumType Reference列出所有系統列舉類型。列舉類型是具名基本值類型，其值是具名的常數，具有基礎整數值。 以下是來自 CSDL 的 AccessRights EnumType。

<EnumType Name="AccessRights">
  <Member Name="None" Value="0" />
  <Member Name="ReadAccess" Value="1" />
  <Member Name="WriteAccess" Value="2" />
  <Member Name="AppendAccess" Value="4" />
  <Member Name="AppendToAccess" Value="16" />
  <Member Name="CreateAccess" Value="32" />
  <Member Name="DeleteAccess" Value="65536" />
  <Member Name="ShareAccess" Value="262144" />
  <Member Name="AssignAccess" Value="524288" />
</EnumType>

另請參閱

使用 Microsoft Dynamics 365 Web API
使用 Web API 驗證 Microsoft Dynamics 365
使用 Web API 執行作業

Microsoft Dynamics 365

© 2017 Microsoft. 著作權所有，並保留一切權利。 著作權