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 sẽ được 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ị một getMetadata phương pháp thông qua nguyên mẫu của nó cho phép bạn 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	Hàm để gọi khi thao tác được thực thi 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 nếu bạn đang thực hiện một yêu cầu CRUD. - 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 trong trường hợp hành động hoặc hàm thực thi được liên kết với bả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, Updatehoặ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ố.

Trả về giá trị

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 đã được 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 những ví dụ sau đây:

• Thực hiện một hành động
• Thực hiện một hàm
• Tạo một bản ghi
• Truy xuất bản ghi
• Cập nhật bản ghi
• Xóa bản ghi
• Liên kết bản ghi
• Hủy liên kết bản ghi

Tiền bo

Bạn có thể 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 một 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 ở đây: 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 một 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 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 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 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 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 bản ghi

Mẫu mã sau đây minh họa cách thực hiện thao tác Associate trên thuộc tính dẫn hướng có giá trị bộ sưu tập (mối quan hệ mộtTo-Many vàTo-Many nhiều). Đối với thuộc tính dẫn hướng đơn giá trị (Mối quan hệ nhiềuTo-One còn gọi là cột Tra cứu), bạn có thể thực hiện thao tác Cập nhật như minh họa ở trên 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 bản ghi

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

Lưu ý

Không giống như thao tác Liên kết cho phép liên kết bản ghi thực thể mục tiêu 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 Disassociate được giới hạn chỉ để hủy liên kết một bản ghi thực thể từ bản ghi thực thể mục tiêu cho 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