Xrm.WebApi.online.execute (Tham khảo API máy khách)

Thực hiện một hành động, hàm hoặc thao tác CRUD đơn lẻ.

Lưu ý

Phương pháp này chỉ được hỗ trợ cho chế độ trực tuyến (Xrm.WebApi.online).

Cú pháp

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

Tham số

Tên	Kiểu	Bắt buộc	Sự miêu tả
request	Đối tượng	Có	Đối tượng mà bạn chuyển đến điểm cuối API Web để thực thi một hành động, hàm hoặc yêu cầu CRUD. Đối tượng hiển thị getMetadata một phương pháp thông qua nguyên mẫu của nó mà bạn sử dụng để xác định siêu dữ liệu cho hành động, hàm hoặc yêu cầu CRUD mà bạn muốn thực hiện. Xem phương thức request.getMetadata
successCallback	Hàm	Không	Một hàm để gọi khi thao tác thành công. Xem Giá trị Trả về
errorCallback	Hàm	Không	Một hàm để gọi khi hoạt động không thành công. Một đối tượng với các thuộc tính sau đây được truyền đi: - errorCode:Số. Mã lỗi dưới dạng số thập phân dương. Ví dụ: mã lỗi được ghi là sẽ 0x80040333 được trả về dưới dạng 2147746611. - message:Xâu. Thông báo lỗi mô tả sự cố.

phương thức request.getMetadata

Phương getMetadata pháp có các tham số sau đây:

Tên	Kiểu	Bắt buộc	Sự miêu tả
boundParameter	String	Không	Tên tham số liên kết cho hành động hoặc hàm cần thực thi. - Chỉ undefined định xem bạn có đang thực hiện yêu cầu CRUD không. - Chỉ định null nếu hành động hoặc hàm thực thi không bị ràng buộc với bất kỳ bảng nào. - Xác định entity xem hành động hoặc hàm thực thi có được liên kết với bảng hay không.
operationName	String	Không	Tên của hành động, hàm hoặc một trong các giá trị sau đây nếu bạn đang thực hiện yêu cầu CRUD: Create, Retrieve, Update, hoặc Delete.
operationType	Số điện thoại	Không	Cho biết loại thao tác bạn đang thực hiện. Xác định một trong các giá trị sau: - 0:Hành động - 1:Chức năng - 2: CRUD
parameterTypes	Đối tượng	Có	Siêu dữ liệu cho các loại tham số. Đối tượng có các giá trị sau: enumProperties : (Tùy chọn) Đối tượng. Siêu dữ liệu cho các kiểu liệt kê. Đối tượng có hai giá trị chuỗi: name và value. structuralProperty :Số. Thể loại của kiểu tham số. Xác định một trong các giá trị sau: - 0:Không biết - 1: PrimitiveType - 2: ComplexType - 3: EnumerationType - 4:Bộ sưu tập - 5: EntityType typeName :Xâu. Tên đủ điều kiện của kiểu tham số.

Giá trị trả về

Khi thành công, trả về đối tượng promise với successCallback các thuộc tính sau:

Tên	Kiểu	Sự miêu tả
body(Phản đối)	Đối tượng	Nội dung phản hồi.
headers	Đối tượng	Tiêu đề phản hồi.
ok	Boolean	Cho biết yêu cầu có thành công hay không.
status	Số điện thoại	Giá trị số trong mã trạng thái phản hồi. Ví dụ: 200
statusText	String	Mô tả mã trạng thái phản hồi. Ví dụ: OK
type(Phản đối)	String	Loại phản hồi. Giá trị là: chuỗi trống (mặc định), arraybuffer, blob, document, json, và text.
url	String	Yêu cầu URL của hành động, chức năng hoặc yêu cầu CRUD mà bạn đã gửi đến điểm cuối API Web.
json	Hứa	Tham số cho đại diện gọi lại thuộc loại bất kỳ (đối tượng JSON).
text	Hứa	Tham số cho đại diện gọi lại là Chuỗi.

Ví dụ

Tìm các ví dụ sau trong các mục sau:

Example	Chứng tỏ
Thực hiện một hành động	Làm thế nào để thực hiện WinOpportunity hành động để đánh dấu một cơ hội là giành được.
Thực hiện một hàm	Cách thực hiện , WhoAmI, CalculateRollupField, RetrieveDuplicatesvà các hàm InitializeFrom và đọc phản hồi của chúng.
Tạo một bản ghi	Làm thế nào để tạo một hồ sơ tài khoản bằng cách sử dụng một đối tượng yêu cầu.
Truy xuất bản ghi	Cách truy xuất tên của hồ sơ tài khoản bằng cách chỉ định ID của nó và các cột cần trả về.
Cập nhật bản ghi	Làm thế nào để cập nhật tên của một hồ sơ tài khoản bằng cách sử dụng một đối tượng yêu cầu.
Xóa bản ghi	Làm thế nào để xóa một hồ sơ tài khoản bằng cách chỉ định bảng và ID của nó.
Liên kết bản ghi	Cách liên kết tài khoản với nhiều liên hệ thông qua thuộc tính dẫn hướng có giá trị bộ sưu tập.
Hủy liên kết bản ghi	Cách loại bỏ liên kết giữa tài khoản và một liên hệ thông qua thuộc tính dẫn hướng có giá trị bộ sưu tập.

Tiền bo

Sử dụng Dataverse REST Builder để tạo mã JavaScript sử dụng phương Xrm.WebApi.online.execute pháp.

Thực hiện ví dụ về hành động

Ví dụ sau đây minh họa cách thực thi hành động WinOpportunity được tìm thấy trong giải pháp Dynamics 365 for Sales. Đối tượng yêu cầu được tạo dựa trên định nghĩa hành động trong hành động Không liên kết.

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
});

Thực hiện ví dụ về hàm

Ví dụ sau đây minh họa cách thực thi hàm 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
});

Ví dụ sau đây minh họa cách thực thi CalculateRollupField hàm:

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
});

Ví dụ sau đây minh họa cách thực thi RetrieveDuplicates hàm:

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
});

Ví dụ sau đây minh họa cách thực thi InitializeFrom hàm:

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
});

Thực hiện thao tác CRUD

Tạo ví dụ về bản ghi

Ví dụ sau đây minh họa cách thực hiện thao tác tạo.

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
});

Truy xuất ví dụ về bản ghi

Ví dụ sau đây minh họa cách thực hiện thao tác truy xuất.

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
});

Cập nhật ví dụ về bản ghi

Ví dụ sau đây minh họa cách thực hiện thao tác cập nhật.

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
});

Xóa một ví dụ về bản ghi

Ví dụ sau đây minh họa cách thực hiện thao tác xóa.

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
});

Liên kết một ví dụ về bản ghi

Mẫu mã sau đây minh họa cách thực hiện thao tác liên kết trên thuộc tính dẫn hướng có giá trị thu thập (mối quan hệ một đối nhiều và nhiều đối nhiều). Đối với thuộc tính dẫn hướng đơn giá trị (mối quan hệ nhiều-một, còn được gọi là cột tra cứu), bạn có thể thực hiện một thao tác cập nhật như minh họa trước đó hoặc sử dụng 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
});

Hủy liên kết ví dụ về bản ghi

Mẫu mã sau đây minh họa cách thực hiện thao tác hủy liên kết trên thuộc tính dẫn hướng có giá trị bộ sưu tập (mối quan hệ một đối nhiều và nhiều đối nhiều). Đối với thuộc tính dẫn hướng đơn giá trị (mối quan hệ nhiều-một, còn được gọi là cột tra cứu), bạn có thể thực hiện một thao tác cập nhật như minh họa trước đó hoặc sử dụng Xrm.WebApi.updateRecord.

Lưu ý

Không giống như thao tác liên kết mà bạn có thể sử dụng để liên kết bản ghi thực thể đích với nhiều bản ghi thực thể liên quan trong một thao tác duy nhất, thao tác hủy liên kết chỉ có thể hủy liên kết một bản ghi thực thể từ bản ghi thực thể đích trong mỗi thao tác.

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
});

Bài viết liên quan

Xrm.WebApi