Xrm.WebApi.online.execute (مرجع واجهة برمجة تطبيقات العميل)

تنفيذ إجراء واحد أو دالة أو عملية CRUD.

إشعار

يتم اعتماد هذا الأسلوب فقط لوضع الاتصال (Xrm.WebApi.online).

بناء الجملة

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

المعلمات

الاسم	نوع	مطلوبة	الوصف
`request`	كائن	نعم	الكائن الذي تمرره إلى نقطة نهاية واجهة برمجة تطبيقات الويب لتنفيذ إجراء أو دالة أو طلب CRUD. يعرض الكائن أسلوبا `getMetadata`عبر النموذج الأولي الخاص به الذي تستخدمه لتعريف بيانات التعريف للإجراء أو الوظيفة أو طلب CRUD الذي تريد تنفيذه. راجع أسلوب request.getMetadata
`successCallback`	الوظيفة	لا	وظيفة للاتصال عند نجاح العملية. راجع القيمة المرجعة
`errorCallback`	الوظيفة	لا	وظيفة للاتصال عند فشل العملية. يتم تمرير كائن بالخصائص التالية: - `errorCode`:رقم. رمز الخطأ كرقم عشري موجب. على سبيل المثال، رمز الخطأ الموثق كما `0x80040333` سيتم إرجاعه ك `2147746611`. - `message`:خيط. رسالة خطأ تصف المشكلة.

أسلوب request.getMetadata

getMetadata يحتوي الأسلوب على المعلمات التالية:

الاسم	نوع	مطلوبة	الوصف
`boundParameter`	سلسلة	لا	اسم المعلمة المرتبطة للإجراء أو الدالة المراد تنفيذها. - حدد `undefined` ما إذا كنت تقوم بتنفيذ طلب CRUD. - حدد `null` ما إذا كان الإجراء أو الدالة المراد تنفيذها غير مرتبطة بأي جدول. - حدد `entity` ما إذا كان الإجراء أو الدالة المراد تنفيذها مرتبطة بجدول.
`operationName`	سلسلة	لا	اسم الإجراء أو الدالة أو إحدى القيم التالية إذا كنت تقوم بتنفيذ طلب CRUD: `Create`أو `RetrieveUpdate`.`Delete`
`operationType`	الرقم‬	لا	يشير إلى نوع العملية التي تنفذها. حدد إحدى القيم التالية: - `0`:فعل - `1`:دالة - `2`:الخام
`parameterTypes`	كائن	نعم	بيانات التعريف الخاصة وأنواع المعلمات. يحتوي الكائن على القيم التالية: `enumProperties` : (اختياري) كائن. بيانات التعريف الخاصة وأنواع التعداد. يحتوي الكائن على قيمتي سلسلة: `name` و `value`. `structuralProperty` :رقم. فئة نوع المعلمة. حدد إحدى القيم التالية: - `0`:مجهول - `1`: نوع بدائي - `2`: ComplexType - `3`: نوع التعداد - `4`:مجموعة - `5`: نوع الكيان `typeName` :خيط. الاسم المؤهل بالكامل لنوع المعلمة.

قيمة الإرجاع

عند النجاح، ترجع عنصر وعد إلى successCallback مع الخصائص التالية:

الاسم	نوع	الوصف
`body`(مهمل)	كائن	نص الاستجابة.
`headers`	كائن	رؤوس الاستجابة.
`ok`	قيمة منطقية	يشير إلى ما إذا كان الطلب ناجحا أم لا.
`status`	الرقم‬	قيمة رقمية في رمز حالة الاستجابة. على سبيل المثال: `200`
`statusText`	سلسلة	وصف رمز حالة الاستجابة. على سبيل المثال: `OK`
`type`(مهمل)	سلسلة	نوع الاستجابة. القيم هي: السلسلة الفارغة (الافتراضية) `arraybuffer`و `blob`و`documentjson`.`text`
`url`	سلسلة	طلب عنوان URL للإجراء أو الدالة أو طلب CRUD الذي أرسلته إلى نقطة نهاية واجهة برمجة تطبيقات الويب.
`json`	وعد	المعلمة إلى مفوض رد الاتصال من أي نوع (كائن JSON).
`text`	وعد	المعلمة إلى مفوض رد الاتصال هي سلسلة.

الأمثلة

ابحث عن هذه الأمثلة في الأقسام التالية:

Example	يوضح
تنفيذ إجراء	كيفية تنفيذ `WinOpportunity` الإجراء لوضع علامة على فرصة على أنها فازت.
تنفيذ دالة	كيفية تنفيذ `WhoAmICalculateRollupFieldRetrieveDuplicates`الدالات و و وقراءة `InitializeFrom` استجاباتها.
إنشاء سجل	كيفية إنشاء سجل حساب باستخدام كائن طلب.
استرداد سجل	كيفية استرداد اسم سجل حساب عن طريق تحديد معرفه والأعمدة المراد إرجاعها.
تحديث سجل	كيفية تحديث اسم سجل حساب باستخدام كائن طلب.
حذف سجل	كيفية حذف سجل حساب عن طريق تحديد الجدول والمعرف الخاصين به.
إقران سجل	كيفية إقران حساب بجهات اتصال متعددة من خلال خاصية تنقل ذات قيمة مجموعة.
إلغاء ازدواز سجل	كيفية إزالة الاقتران بين حساب جهة اتصال واحدة من خلال خاصية تنقل ذات قيمة مجموعة.

تلميح

استخدم Dataverse REST Builder لإنشاء التعليمات البرمجية Xrm.WebApi.online.execute JavaScript التي تستخدم الأسلوب .

تنفيذ مثال إجراء

يوضح المثال التالي كيفية تنفيذ الإجراء الموجود WinOpportunity في حل Dynamics 365 for Sales. يتم إنشاء كائن الطلب استنادا إلى تعريف الإجراء في الإجراءات غير الواردة.

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

إقران مثال سجل

يوضح نموذج التعليمات البرمجية التالي كيفية تنفيذ عملية إقران على خصائص التنقل ذات القيمة المجمعة (علاقات واحد إلى متعدد وعلاقات متعدد إلى متعدد). بالنسبة لخصائص التنقل ذات القيمة الواحدة (علاقات متعدد إلى واحد، والمعروفة أيضا بأعمدة البحث)، يمكنك تنفيذ عملية تحديث كما هو موضح سابقا أو استخدام 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
});

فصل مثال سجل

يوضح نموذج التعليمات البرمجية التالي كيفية تنفيذ عملية إلغاء اقتران على خصائص التنقل ذات القيمة المجمعة (علاقات واحد إلى متعدد وعلاقات متعدد إلى متعدد). بالنسبة لخصائص التنقل ذات القيمة الواحدة (علاقات متعدد إلى واحد، والمعروفة أيضا بأعمدة البحث)، يمكنك تنفيذ عملية تحديث كما هو موضح سابقا أو استخدام Xrm.WebApi.updateRecord.