撰寫 HTTP 要求並處理錯誤

  • 發行項

 

發行︰ 2017年1月

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

您可以透過撰寫和傳送 HTTP 要求與 Web API 互動。 您需要知道如何設定適當的 HTTP 標題，並處理回覆中的任何錯誤。

本主題內容

Web API URL 和版本

HTTP 方法

HTTP 標頭

識別狀態碼

從回覆剖析錯誤

Web API URL 和版本

若要存取 Web API，您必須使用下表中的元件撰寫 URL。

項目

描述

通訊協定

適當的通訊協定：https:// 或 http://。

基底 URL

這通常是您用來開啟 Web 應用程式的 URL。

  • 對於 Microsoft Dynamics 365 (線上)：使用 <tenant name>.crm.dynamics.com。

  • 對於 網際網路對向部署 (IFD)：使用您的執行個體的適當 URL。 這將會是：<organization name>.<domain name>。

  • 對於 Dynamics 365 (內部部署)：使用 <server name>/<organization name>

Web API 路徑

Web API 的路徑為 /api/data/。

版本

版本以這種方式表示：v[Major_version].[Minor_version][PatchVersion]/。 這個版本的有效版本如下：

  • v8.0/ 適用於 Microsoft Dynamics CRM Online 2016 更新 0.1 和 Microsoft Dynamics CRM 2016 更新 0.1

  • v8.1/ 適用於 Microsoft Dynamics CRM Online 2016 更新 1 和 Microsoft Dynamics CRM 2016 Service Pack 1

  • Dynamics 365 (Online 和內部部署) 的 2016 年 12 月更新 的 v8.2/

您使用的特定值對此版本並不重要，只要您已套用對應的更新或 Service Pack 即可。 其他資訊：版本相容性

資源

您想要使用的實體、函數或動作的名稱。

您會使用的 URL 將以下列組件來撰寫：通訊協定 + 基底 URL + Web API 路徑 + 版本 + 資源。

版本相容性

我們已在此版本套用一些有關更新或 Service Pack 的累加變更。 套用這些更新時，就已將相同的功能新增至後續的次要版本。 因此，如果您可以使用 8.2 版，則 8.1 和 8.0 版就會有相同的功能。 這可能是因為所有的變更都已經是解決 Microsoft Dynamics 365 Web API 限制中所列之項目的累加或錯誤修正。 未引進任何重大變更。

注意

下一個主要版本 (v9) 會引進只有使用該版本才能取得的功能。 後續的次要版本可能會提供無法回溯移植到較早次要版本的額外功能。 當您使用的 URL 參考 v8.2 時，針對 v8.x 所撰寫的程式碼將會繼續在 v9.x 中運作。

對於 v8.x 版本，既已知道此主要版本中的更新或 Service Pack 並沒有引進重大變更，請使用您所能使用的最新版本。 但這種情形在未來版本中會有所改變，您將需要注意您所處理之服務的版本。

HTTP 方法

HTTP 要求可以套用各種不同的方法。 使用 Web API 時，您只會使用下表中列出的方法。

方法

使用方式

GET

擷取資料時使用，包括呼叫函數。 預期的成功擷取狀態碼為 200 OK 時。

POST

建立實體或呼叫動作時使用。

PATCH

更新實體或執行 upsert 作業時使用。

DELETE

刪除實體或實體的個別屬性時使用。

PUT

在受限情況下用來更新實體的個別屬性。 此方法不建議在更新大部分實體時使用。 您會在更新模型實體時使用此方法。

HTTP 標頭

雖然 OData 通訊協定同時允許 JSON 與 ATOM 這兩種格式，但 Web API 僅支援 JSON。 因此，可以套用下列標頭。

每個要求應包含 Accept 標頭值 application/json，即使不預期任何回覆本文時。 回覆中傳回的任何錯誤都會傳回為 JSON。 即使未包括此標頭，您的程式碼仍能運作，但是建議的最佳做法是包括它。

最新的 OData 版本為 4.0，但是未來的版本可能納入新功能。 若要確認未來套用至程式碼的 OData 版本不會混淆，您應該要包括程式碼中套用的最新版和最高版本 OData 的明確陳述。 同時使用 OData-Version 和 OData-MaxVersion 標頭，且值設為 4.0。

所有 HTTP 標頭都應至少包括下列標頭。

Accept: application/json OData-MaxVersion: 4.0 OData-Version: 4.0

每個要求的要求本文中包括 JSON 資料時，必須包括 Content-Type 標頭且其值為 application/json。

Content-Type: application/json

您可以使用其他標頭啟用特定功能。

  • 在實體的建立 (POST) 或更新 (PATCH) 作業時傳回資料，包括 return=representation 偏好。 此偏好套用至 POST 要求時，成功的回覆狀態會是 201 (Created)。 若是 PATCH 要求，成功的回覆狀態會是 200 (OK)。 未套用此偏好時，兩種作業都會傳回狀態 204 (No Content)，反映預設回覆的本文中未傳回任何資料。

    注意

    此功能已在 Dynamics 365 (Online 和內部部署) 的 2016 年 12 月更新 新增。

  • 若要透過查詢傳回格式化的值，請使用 Prefer 標頭來加入設定為 Microsoft.Dynamics.CRM.formattedvalue 的 odata.include-annotations 喜好設定。其他資訊：包含格式化的值

  • 您也可以使用 Prefer 標頭與 odata.maxpagesize 選項指定要傳回的頁面數目。其他資訊：指定頁面中要傳回的實體數目

  • 若要模擬其他使用者，當呼叫端有權這樣做實，請新增 MSCRMCallerID 標頭並包含要模擬的使用者的 systemuserid 值。其他資訊：使用 Web API 模擬其他使用者。

  • 若要套用開放式並行存取，您可以套用值為 Etag 的 If-Match 標頭。其他資訊：套用開放式並行存取。

  • 若要針對 POST 要求啟用重複資料偵測，您可以使用 MSCRM.SuppressDuplicateDetection: false 標頭。其他資訊：244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

  • 若要控制 upsert 作業是否應該實際建立或更新的實體，您也可以使用 If-Match 和 If-None-Match 標頭。其他資訊：Upsert 實體。

  • 當您執行批次作業時，您必須在要求中套用多個不同的標頭，且在本文中傳送各部分。其他資訊：使用 Web API，執行批次作業。

識別狀態碼

無論 HTTP 要求成功或失敗，回覆都會包含狀態碼。Microsoft Dynamics 365 Web API 傳回的狀態碼包括下列內容。

代碼

描述

類型​​

200 OK

如果您的作業會在回覆本文中傳回資料，則預期會是此回覆。

成功

201 Created

當您的實體 POST 作業成功，且您已在要求中指定 return-representation 偏好，請預期此情況。

注意

此功能已在 Dynamics 365 (Online 和內部部署) 的 2016 年 12 月更新 新增。

成功

204 No Content

如果您的作業成功，但未在回覆本文中傳回資料，則預期會是此回覆。

成功

304 Not Modified

測試實體自上次擷取後是否已修改時，預期會是此回覆。其他資訊：條件擷取

重新導向

403 Forbidden

下列類型的錯誤預期會是此回覆：

  • AccessDenied

  • AttributePermissionReadIsMissing

  • AttributePermissionUpdateIsMissingDuringUpdate

  • AttributePrivilegeCreateIsMissing

  • CannotActOnBehalfOfAnotherUser

  • CannotAddOrActonBehalfAnotherUserPrivilege

  • CrmSecurityError

  • InvalidAccessRights

  • PrincipalPrivilegeDenied

  • PrivilegeCreateIsDisabledForOrganization

  • PrivilegeDenied

  • unManagedinvalidprincipal

  • unManagedinvalidprivilegeedepth

用戶端錯誤

401 Unauthorized

下列類型的錯誤預期會是此回覆：

  • BadAuthTicket

  • ExpiredAuthTicket

  • InsufficientAuthTicket

  • InvalidAuthTicket

  • InvalidUserAuth

  • MissingCrmAuthenticationToken

  • MissingCrmAuthenticationTokenOrganizationName

  • RequestIsNotAuthenticated

  • TamperedAuthTicket

  • UnauthorizedAccess

  • UnManagedInvalidSecurityPrincipal

用戶端錯誤

413 Payload Too Large

要求長度過長時，預期會是此回覆。

用戶端錯誤

400 BadRequest

引數無效時，預期會是此回覆。

用戶端錯誤

404 Not Found

當資源不存在時，預期會是此回覆。

用戶端錯誤

405 Method Not Allowed

不正確的方法與資源組合，會發生此錯誤。 例如，您不可在實體集上使用 DELETE 或 PATCH。

下列類型的錯誤預期會是此回覆：

  • CannotDeleteDueToAssociation

  • InvalidOperation

  • NotSupported

用戶端錯誤

412 Precondition Failed

下列類型的錯誤預期會是此回覆：

  • ConcurrencyVersionMismatch

  • DuplicateRecord

用戶端錯誤

500 Internal Server Error

當建立實體的 POST 要求啟用重複資料偵測，且要建立的實體為重複資料時，預期會是此回覆。其他資訊：244259ca-2fbc-4fd4-9a74-6166e6683355#bkmk_SuppressDuplicateDetection

伺服器錯誤

501 Not Implemented

某些要求的作業未實作時，預期會是此回覆。

伺服器錯誤

503 Service Unavailable

當 Web API 服務無法使用時，預期會是此回覆。

伺服器錯誤

從回覆剖析錯誤

關於錯誤的詳細資料做為 JSON 包含在回覆中。 錯誤會是此格式。

    { "error":{ "code": "
            <This code is not related to the http status code and is frequently empty>", "message": "
            <A message describing the error>", "innererror": { "message": "
            <A message describing the error, this is frequently the same as the outer message>", "type": "Microsoft.Crm.CrmHttpException", "stacktrace": "
            <Details from the server about where the error occurred>" } } }

另請參閱

使用 Web API 執行作業
使用 Web API 查詢資料
使用 Web API，建立實體
使用 Web API 擷取實體
使用 Web API 更新和刪除實體
使用 Web API 建立和取消實體的關聯
使用 Web API 功能
使用 Web API 動作
使用 Web API，執行批次作業
使用 Web API 模擬其他使用者
使用 Web API 執行條件運算

Microsoft Dynamics 365

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