Xrm.WebApi.online.execute （用戶端 API 參考）

執行單一動作、函數或 CRUD 作業。

備註

此方法僅支援線上模式 （Xrm.WebApi.online）。

語法

Xrm.WebApi.online.execute(request).then(successCallback, errorCallback);

參數

名稱	類型	為必填項目	Description
request	物體	Yes	將傳遞至 Web API 端點以執行動作、函式或 CRUD 要求的物件。 物件會透過其原型公開方法getMetadata，讓您定義要執行的動作、函式或 CRUD 要求的中繼資料。 請參閱 request.getMetadata 方法
successCallback	功能	否	操作執行成功時要呼叫的函數。 請參閱 傳回值
errorCallback	功能	否	作業失敗時要呼叫的函式。 會傳遞具有下列屬性的物件： - errorCode：數。 錯誤碼為正十進位數。 例如，記載為 0x80040333 的錯誤碼將傳回為 2147746611。 - message：繩子。 描述問題的錯誤訊息。

request.getMetadata 方法

該 getMetadata 方法具有以下參數：

名稱	類型	為必填項目	Description
boundParameter	繩子	否	要執行的動作或函數的繫結參數名稱。 - 指定 undefined 您是否正在執行 CRUD 要求。 - 指定 null 要執行的動作或函數是否未繫結至任何表格。 - 指定 entity 要執行的動作或函數是否繫結到表格。
operationName	繩子	否	動作、函數的名稱，或下列其中一個值（如果您正在執行 CRUD 要求 Create）：、 Retrieve、 Update或 Delete。
operationType	Number	否	指出您正在執行的作業類型;指定下列其中一個值： - 0：動作 - 1：作用 - 2： 粗魯
parameterTypes	物體	Yes	參數類型的中繼資料。 物件具有下列值： enumProperties ： （選擇性） 物件。 列舉類型的中繼資料。 物件有兩個字串值： name 和 value structuralProperty ：數。 參數類型的類別。 指定下列其中一個值： - 0：生 - 1： 基本類型 - 2： 複雜類型 - 3： 枚舉類型 - 4：集合 - 5： 實體類型 typeName ：繩子。 參數類型的完整名稱。

傳回值

成功時，會傳回具有下列屬性的 Promise successCallback 物件：

名稱	類型	Description
body（已棄用）	物體	回應內文。
headers	物體	回應標頭。
ok	布林值	指出要求是否成功。
status	Number	回應狀態碼中的數值。 例如：200
statusText	繩子	回應狀態碼的描述。 例如：OK
type（已棄用）	繩子	回應類型。 值為：空字串 （預設值）、 arraybuffer、 blobdocumentjsontext和 。
url	繩子	傳送至 Web API 端點之動作、函式或 CRUD 要求的要求 URL。
json	答應	回呼委派的參數類型為 any （JSON 物件）。
text	答應	回呼委派的參數是 String。

範例

在下面找到這些例子：

• 執行動作
• 執行函數
• 建立記錄
• 擷取記錄
• 更新記錄
• 刪除記錄
• 關聯記錄
• 取消記錄關聯

小提示

您可以使用 Dataverse REST 產生器 來產生使用該 Xrm.WebApi.online.execute 方法的 JavaScript 程式碼。

執行動作

下列範例示範如何執行在 Dynamics 365 for Sales 解決方案中找到的 WinOpportunity 動作。 請求物件是根據此處的動作定義建立的： 未繫結的動作

var Sdk = window.Sdk || {};
/**
 * Request to win an opportunity
 * @param {Object} opportunityClose - The opportunity close activity associated with this state change.
 * @param {number} status - Status of the opportunity.
 */
Sdk.WinOpportunityRequest = function(opportunityClose, status) {
    this.OpportunityClose = opportunityClose;
    this.Status = status;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.WinOpportunityRequest.prototype.getMetadata = function () {
    return {
        boundParameter: null,
        parameterTypes: {
            "OpportunityClose": {
                "typeName": "mscrm.opportunityclose",
                "structuralProperty": 5 // Entity Type
            },
            "Status": {
                "typeName": "Edm.Int32",
                "structuralProperty": 1 // Primitive Type
            }
        },
        operationType: 0, // This is an action. Use '1' for functions and '2' for CRUD
        operationName: "WinOpportunity",
    };
};

var opportunityClose = {
    "opportunityid@odata.bind": "/opportunities(c60e0283-5bf2-e311-945f-6c3be5a8dd64)",
    "description": "Product and maintenance for 2018",
    "subject": "Contract for 2018"
}

// Construct a request object from the metadata
var winOpportunityRequest = new Sdk.WinOpportunityRequest(opportunityClose, 3);

// Use the request object to execute the function
Xrm.WebApi.online.execute(winOpportunityRequest).then(function (response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);
        // The WinOpportunityRequest does not return any response body content. So we
        // need not access the response.json() property.

        // Perform other operations as required.
    }
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

執行函數

下列範例示範如何執行 WhoAmI 函式：

var Sdk = window.Sdk || {};
/**
 * Request to execute WhoAmI function
 */
Sdk.WhoAmIRequest = function () { };

// NOTE: The getMetadata property should be attached to the function prototype instead of the
//       function object itself.
Sdk.WhoAmIRequest.prototype.getMetadata = function () {
    return {
        boundParameter: null,
        parameterTypes: {},
        operationType: 1, // This is a function. Use '0' for actions and '2' for CRUD
        operationName: "WhoAmI",
    };
};

// Construct a request object from the metadata
var whoAmIRequest = new Sdk.WhoAmIRequest();

// Use the request object to execute the function
Xrm.WebApi.online.execute(whoAmIRequest)
.then(function (response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);

        // Use response.json() to access the content of the response body.
        return response.json();
    }
}
)
.then(function (responseBody) {
    console.log("User Id: %s", responseBody.UserId);
    // perform other operations as required;
})
.catch(function (error) {
    console.log(error.message);
    // handle error conditions
});

下列範例示範如何執行 CalculateRollupField 函式：

var Sdk = window.Sdk || {};

Sdk.CalculateRollupFieldRequest = function(target, fieldName) {
    this.Target = target;
    this.FieldName = fieldName;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
//       function object itself.
Sdk.CalculateRollupFieldRequest.prototype.getMetadata = function() {
    return {
        boundParameter: null,
        parameterTypes: {
            "Target": {
                "typeName": "mscrm.crmbaseentity",
                "structuralProperty": 5
            },
            "FieldName": {
                "typeName": "Edm.String",
                "structuralProperty": 1
            }
        },
        operationType: 1, // This is a function. Use '0' for actions and '2' for CRUD
        operationName: "CalculateRollupField"
    };
};

// Create variables to point to a quote record and to a specific column
var quoteId = {
    "@odata.type": "Microsoft.Dynamics.CRM.quote",
    "quoteid": "7bb01e55-2394-ea11-a811-000d3ad97943"
};

// The roll-up column for which we want to force a re-calculation
var fieldName = "new_test_rollup";

// Create variable calculateRollupFieldRequest and pass those variables created above
var calculateRollupFieldRequest = new Sdk.CalculateRollupFieldRequest(quoteId, fieldName);

// Use the request object to execute the function
Xrm.WebApi.online.execute(calculateRollupFieldRequest)
.then(function(response) {
    if (response.ok) { // If a response was received.
        console.log("Status: %s %s", response.status, response.statusText);

        // Use response.json() to access the content of the response body.
        return response.json();
    }
})
.then(function(responseBody) { 
    //Do something with the response
    console.log("The response is: %s", responseBody);
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

下列範例示範如何執行 RetrieveDuplicates 函式：

var Sdk = window.Sdk || {};

Sdk.RetrieveDuplicatesRequest = function(businessEntity, matchingEntityName, pagingInfo) {
    this.BusinessEntity = businessEntity;
    this.MatchingEntityName = matchingEntityName;
    this.PagingInfo = pagingInfo;

};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.RetrieveDuplicatesRequest.prototype.getMetadata = function() {
    return {
        boundParameter: null,
        parameterTypes: {
            "BusinessEntity": {
                "typeName": "mscrm.crmbaseentity",
                "structuralProperty": 5 // Entity Type
            },
            "MatchingEntityName": {
                "typeName": "Edm.String",
                "structuralProperty": 1 // Primitive Type
            },
            "PagingInfo": {
                "typeName:": "mscrm.PagingInfo", // Complex Type
                "structuralProperty": 5
            }
        },
        operationType: 1, // This is a function. Use '0' for actions and '2' for CRUD
        operationName: "RetrieveDuplicates",
    };
};

// Create a variable to point to a contact record and with specific data in the needed columns
var contactRecord = {
    "@odata.type": "Microsoft.Dynamics.CRM.contact",
    "firstname": "Test",
    "lastname": "Account"
};

// Create a paging object to keep track of the current page and how many records we get per page
var pagingInfo = {
    "PageNumber": 1,
    "Count": 10
};

// Create the variable retrieveDuplicatesRequest to build the request
var retrieveDuplicatesRequest = new Sdk.RetrieveDuplicatesRequest(contactRecord, "contact", pagingInfo);

// Use the request object to execute the function
Xrm.WebApi.online.execute(retrieveDuplicatesRequest)
.then(function (response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);

        // Use response.json() to access the content of the response body.
        return response.json();
    }
})
.then(function(responseBody) { 
    // Do something with the response
    console.log("The response is: %s", responseBody);
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

下列範例示範如何執行 InitializeFrom 函式：

var Sdk = window.Sdk || {};

Sdk.InitializeFromRequest = function (
  entityMoniker,
  targetEntityName,
  targetFieldType
) {
  this.EntityMoniker = entityMoniker;
  this.TargetEntityName = targetEntityName;
  this.TargetFieldType = targetFieldType;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.InitializeFromRequest.prototype.getMetadata = function () {
  return {
    boundParameter: null,
    parameterTypes: {
      EntityMoniker: {
        typeName: "mscrm.crmbaseentity",
        structuralProperty: 5, //Entity Type
      },
      TargetEntityName: {
        typeName: "Edm.String",
        structuralProperty: 1, // PrimitiveType
      },
      TargetFieldType: {
        typeName: "Microsoft.Dynamics.CRM.TargetFieldType",
        structuralProperty: 3, // Enum Type
        enumProperties: [
          {
            name: "All",
            value: 0,
          },
          {
            name: "ValidForCreate",
            value: 1,
          },
          {
            name: "ValidForUpdate",
            value: 2,
          },
          {
            name: "ValidForRead",
            value: 3,
          },
        ],
      },
    },
    operationType: 1, // This is a function. Use '0' for actions and '2' for CRUD
    operationName: "InitializeFrom",
  };
};

// Create a variable to point to tje parent account record
var parentAccountRecord = {
  "@odata.type": "Microsoft.Dynamics.CRM.account",
  accountid: "141da047-eaad-eb11-b1b4-000d3ac581a0",
};

// Create a variable for the target entity name
var targetEntityName = "account";

// Create a variable for the target field type
var targetFieldType = 0;

// Build the request
var initializeFromRequest = new Sdk.InitializeFromRequest(
  parentAccountRecord,
  targetEntityName,
  targetFieldType
);

// Execute the request
Xrm.WebApi.online.execute(initializeFromRequest)
.then(function (response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);

        // Use response.json() to access the content of the response body.
        return response.json();
    }
})
.then(function(responseBody) { 
    // Do something with the response
    console.log("The response is: %s", responseBody);
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

執行 CRUD 作業

建立記錄

下列範例示範如何執行建立作業。

var Sdk = window.Sdk || {};

/**
 * Request to execute a create operation
 */
Sdk.CreateRequest = function(entityName, payload) {
    this.etn = entityName;
    this.payload = payload;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.CreateRequest.prototype.getMetadata = function () {
    return {
        boundParameter: null,
        parameterTypes: {},
        operationType: 2, // This is a CRUD operation. Use '0' for actions and '1' for functions
        operationName: "Create",
    };
};
// Construct a request object from the metadata
var payload = {
    name: "Fabrikam Inc."
};
var createRequest = new Sdk.CreateRequest("account", payload);

// Use the request object to execute the function
Xrm.WebApi.online.execute(createRequest)
.then(function (response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);
        
        // The Create request does not return any response body content. So we
        // need not access the response.json() property.

        // Perform other operations as required.
    }
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

擷取記錄

下列範例示範如何執行擷取作業。

var Sdk = window.Sdk || {};

/**
 * Request to execute a retrieve operation
 */
Sdk.RetrieveRequest = function(entityReference, columns) {
    this.entityReference = entityReference;
    this.columns = columns;
};
// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.RetrieveRequest.prototype.getMetadata = function () {
    return {
        boundParameter: null,
        parameterTypes: {},
        operationType: 2, // This is a CRUD operation. Use '0' for actions and '1' for functions
        operationName: "Retrieve",
    };
};

// Construct request object from the metadata
var entityReference = {
    entityType: "account",
    id: "d2b6c3f8-b0fa-e911-a812-000d3a59fa22"
};
var retrieveRequest = new Sdk.RetrieveRequest(entityReference, ["name"]);

// Use the request object to execute the function
Xrm.WebApi.online.execute(retrieveRequest)
.then(function (response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);

        // Use response.json() to access the content of the response body.
        return response.json();
    }
})
.then(function(responseBody) {
    console.log("Name: %s", responseBody.name);
    
    // perform other operations as required;
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

更新記錄

下列範例示範如何執行更新作業。

var Sdk = window.Sdk || {};


/**
 * Request to execute an update operation
 */
Sdk.UpdateRequest = function(entityName, entityId, payload) {
    this.etn = entityName;
    this.id = entityId;
    this.payload = payload;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.UpdateRequest.prototype.getMetadata = function () {
    return {
        boundParameter: null,
        parameterTypes: {},
        operationType: 2, // This is a CRUD operation. Use '0' for actions and '1' for functions
        operationName: "Update",
    };
};

// Construct a request object from the metadata
var payload = {
    name: "Updated Sample Account"
};
var updateRequest = new Sdk.UpdateRequest("account", "d2b6c3f8-b0fa-e911-a812-000d3a59fa22", payload);

// Use the request object to execute the function
Xrm.WebApi.online.execute(updateRequest)
.then(function (response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);

        // The Update request does not return any response body content. So we
        // need not access the response.json() property.
        
        // perform other operations as required;
    }
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

刪除記錄

下列範例示範如何執行刪除作業。

var Sdk = window.Sdk || {};

/**
 * Request to execute a delete operation
 */
Sdk.DeleteRequest = function(entityReference) {
    this.entityReference = entityReference;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.DeleteRequest.prototype.getMetadata = function () {
        return {
            boundParameter: null,
            parameterTypes: {},
            operationType: 2, // This is a CRUD operation. Use '0' for actions and '1' for functions
            operationName: "Delete",
        };
    };
};
};

// Construct request object from the metadata
var entityReference = {
    entityType: "account",
    id: "d2b6c3f8-b0fa-e911-a812-000d3a59fa22"
};
var deleteRequest = new Sdk.DeleteRequest(entityReference);

// Use the request object to execute the function
Xrm.WebApi.online.execute(deleteRequest)
.then(function(response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);
        
        // The Delete request does not return any response body content. So we
        // need not access the response.json() property.

        // perform other operations as required;
    }
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

關聯記錄

下列程式碼範例示範如何對集合值導覽屬性 （一To-Many 和多To-Many 關聯性） 執行 Associate 作業。 針對單一值導覽屬性 （多To-One 關聯性，也稱為查閱資料行） ，您可以執行如上所示的更新作業，或使用 Xrm.WebApi.updateRecord。

var Sdk = window.Sdk || {};

/*
 * Request to execute an Associate operation.
 */
Sdk.AssociateRequest = function(target, relatedEntities, relationship) {
    this.target = target;
    this.relatedEntities = relatedEntities;
    this.relationship = relationship;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.AssociateRequest.prototype.getMetadata = function() {
    return {
        boundParameter: null,
        parameterTypes: {},
        operationType: 2, // Associate and Disassociate fall under the CRUD umbrella
        operationName: "Associate"
    }
};

// Construct the target EntityReference object
var target = {
    entityType: "account",
    id: "0b4abc7d-7619-eb11-8dff-000d3ac5c7f9"
};

// Construct the related EntityReferences that the Target will be associated with.
var relatedEntities = [
    {
        entityType: "contact",
        id: "180a9aad-7619-eb11-8dff-000d3ac5c7f9"
    },
    {
        entityType: "contact",
        id: "753c58b4-7619-eb11-8dff-000d3ac5c7f9"
    }
];

// The name of the existing relationship to associate on.
var relationship = "new_account_contact";

var manyToManyAssociateRequest = new Sdk.AssociateRequest(target, relatedEntities, relationship)

Xrm.WebApi.online.execute(manyToManyAssociateRequest)
.then(function(response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);

        // The Associate request does not return any response body content. So we
        // need not access the response.json() property.

        // perform other operations as required;
    }
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

取消記錄關聯

下列程式碼範例示範如何對集合值導覽屬性 （一To-Many 和多To-Many 關聯性） 執行取消關聯作業。 針對單一值導覽屬性 （多To-One 關聯性，也稱為查閱資料行） ，您可以執行如上所示的更新作業，或使用 Xrm.WebApi.updateRecord。

備註

與允許在單一作業中將目標實體記錄與多個相關實體記錄相關聯的「關聯」作業不同，「取消關聯」作業僅限於每個作業只能取消一個實體記錄與目標實體記錄的關聯。

var Sdk = window.Sdk || {};

/*
 * Request to execute a Disassociate operation.
 */
Sdk.DisassociateRequest = function(target, relatedEntityId, relationship) {
    this.target = target;
    this.relatedEntityId = relatedEntityId;
    this.relationship = relationship;
};

// NOTE: The getMetadata property should be attached to the function prototype instead of the
// function object itself.
Sdk.DisassociateRequest.prototype.getMetadata = function() {
    return {
        boundParameter: null,
        parameterTypes: {},
        operationType: 2, // Associate and Disassociate fall under the CRUD umbrella
        operationName: "Disassociate"
    }
};

// Construct the target EntityReference object
var target = {
    entityType: "account",
    id: "0b4abc7d-7619-eb11-8dff-000d3ac5c7f9"
};

// The GUID of the related entity record to disassociate.
var relatedEntityId = "180a9aad-7619-eb11-8dff-000d3ac5c7f9";

// The name of the existing relationship to disassociate from.
var relationship = "new_account_contact";

var manyToManyDisassociateRequest = new Sdk.DisassociateRequest(target, relatedEntityId, relationship)

Xrm.WebApi.online.execute(manyToManyDisassociateRequest)
.then(function(response) {
    if (response.ok) {
        console.log("Status: %s %s", response.status, response.statusText);

        // The Disassociate request does not return any response body content. So we
        // need not access the response.json() property.

        // perform other operations as required;
    }
})
.catch(function(error) {
    console.log(error.message);
    // handle error conditions
});

相關文章

Xrm.WebApi