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 中定義的詞彙清單，您應了解。

服務文件

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

服務文件

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

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

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

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

CSDL 中繼資料文件

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

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

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

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

實體類型

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 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。

屬性

每個實體類型都可能有回應屬性的宣告屬性。 在 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 基本值類型。

查詢屬性

對於大部分的單一值導覽屬性，您會發現有計算的唯讀屬性，它使用下列命名慣例：_<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. 著作權所有，並保留一切權利。 著作權