Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Execute uma única ação, função ou operação CRUD.
Observação
Esse método tem suporte apenas para o modo online (Xrm.WebApi.online).
Sintaxe
Xrm.WebApi.online.execute(request).then(successCallback, errorCallback);
Parâmetros
| Nome | Tipo | Obrigatório | Description |
|---|---|---|---|
request |
Object | Yes | Objeto que você passa para o ponto de extremidade da API Web para executar uma ação, uma função ou uma solicitação CRUD. O objeto expõe um getMetadata método por meio de seu protótipo que você usa para definir os metadados para a ação, função ou solicitação CRUD que você deseja executar. Consulte o método request.getMetadata |
successCallback |
Função | Não | Uma função a ser chamada quando a operação for bem-sucedida. Consulte o valor retornado |
errorCallback |
Função | Não | Uma função a ser chamada quando a operação falhar. Um objeto com as seguintes propriedades é passado: - errorCode:Número. O código de erro como um número decimal positivo. Por exemplo, o código de erro documentado como 0x80040333 será retornado como 2147746611.- message:Corda. Uma mensagem de erro descrevendo o problema. |
Método request.getMetadata
O getMetadata método tem os seguintes parâmetros:
| Nome | Tipo | Obrigatório | Description |
|---|---|---|---|
boundParameter |
String | Não | O nome do parâmetro associado para a ação ou função a ser executada. - Especifique undefined se você está executando uma solicitação CRUD.– Especifique null se a ação ou função a ser executada não está associada a nenhuma tabela.- Especifique entity se a ação ou função a ser executada está associada a uma tabela. |
operationName |
String | Não | Nome da ação, função ou um dos seguintes valores se você estiver executando uma solicitação CRUD: Create, , Retrieve, Updateou Delete. |
operationType |
Número | Não | Indica o tipo de operação que você está executando. Especifique um dos seguintes valores: - 0:Ação- 1:Função- 2:CRUD |
parameterTypes |
Object | Yes | Os metadados para tipos de parâmetro. O objeto tem os seguintes valores:enumProperties : objeto (opcional). Os metadados para tipos de enumeração. O objeto tem dois valores de cadeia de caracteres: name e value.structuralProperty :Número. A categoria do tipo de parâmetro. Especifique um dos seguintes valores:- 0:Desconhecido- 1: PrimitiveType- 2: ComplexType- 3: EnumerationType- 4:Coleção- 5: EntityTypetypeName :Corda. O nome totalmente qualificado do tipo de parâmetro. |
Valor de devolução
Com êxito, retorna um objeto de promessa para as successCallback seguintes propriedades:
| Nome | Tipo | Description |
|---|---|---|
body(Preterido) |
Object | Corpo da resposta. |
headers |
Object | Cabeçalhos de resposta. |
ok |
booleano | Indica se a solicitação foi bem-sucedida. |
status |
Número | Valor numérico no código de status de resposta. Por exemplo: 200 |
statusText |
String | Descrição do código de status de resposta. Por exemplo: OK |
type(Preterido) |
String | Tipo de resposta. Os valores são: a cadeia de caracteres vazia (padrão), arraybuffer, , , blobe documentjson. text |
url |
String | Solicite a URL da ação, função ou solicitação CRUD que você enviou para o ponto de extremidade da API Web. |
json |
Prometer | O parâmetro para o delegado de retorno de chamada é do tipo qualquer (objeto JSON). |
text |
Prometer | O parâmetro para o delegado de retorno de chamada é uma cadeia de caracteres. |
Exemplos
Encontre estes exemplos nas seções a seguir:
| Exemplo | Demonstra |
|---|---|
| Executar uma ação | Como executar a ação WinOpportunity para marcar uma oportunidade como ganha. |
| Executar uma função | Como executar as WhoAmIfunções, CalculateRollupFieldRetrieveDuplicatesfunções e InitializeFrom funções e ler suas respostas. |
| Criar um registro | Como criar um registro de conta usando um objeto de solicitação. |
| Recuperar um registro | Como recuperar o nome de um registro de conta especificando sua ID e as colunas a serem retornadas. |
| Atualizar um registro | Como atualizar o nome de um registro de conta usando um objeto de solicitação. |
| Excluir um registro | Como excluir um registro de conta especificando sua tabela e ID. |
| Associar um registro | Como associar uma conta a vários contatos por meio de uma propriedade de navegação com valor de coleção. |
| Desassociar um registro | Como remover a associação entre uma conta e um contato por meio de uma propriedade de navegação com valor de coleção. |
Dica
Use o Construtor REST do Dataverse para gerar código JavaScript que usa o Xrm.WebApi.online.execute método.
Executar um exemplo de ação
O exemplo a seguir demonstra como executar a ação WinOpportunity encontrada na solução Dynamics 365 for Sales. O objeto de solicitação é criado com base na definição de ação em ações não associados.
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
});
Executar um exemplo de função
O exemplo a seguir demonstra como executar a função 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
});
O exemplo a seguir demonstra como executar a CalculateRollupField função:
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
});
O exemplo a seguir demonstra como executar a RetrieveDuplicates função:
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
});
O exemplo a seguir demonstra como executar a InitializeFrom função:
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
});
Executar operações CRUD
Criar um exemplo de registro
O exemplo a seguir demonstra como executar uma operação de criaçã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
});
Recuperar um exemplo de registro
O exemplo a seguir demonstra como executar uma operação de recuperação.
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
});
Atualizar um exemplo de registro
O exemplo a seguir demonstra como executar uma operação de atualização.
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
});
Excluir um exemplo de registro
O exemplo a seguir demonstra como executar uma operação de exclusão.
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
});
Associar um exemplo de registro
O exemplo de código a seguir demonstra como executar uma operação associada em propriedades de navegação com valor de coleção (relações um para muitos e muitos para muitos). Para propriedades de navegação com valor único (relações muitos para um, também conhecidas como colunas de pesquisa), você pode executar uma operação de atualização conforme mostrado anteriormente ou usar 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
});
Desassociar um exemplo de registro
O exemplo de código a seguir demonstra como executar uma operação desassociar em propriedades de navegação com valor de coleção (relações um para muitos e muitos para muitos). Para propriedades de navegação com valor único (relações muitos para um, também conhecidas como colunas de pesquisa), você pode executar uma operação de atualização conforme mostrado anteriormente ou usar Xrm.WebApi.updateRecord.
Observação
Ao contrário da operação de associação, que você pode usar para associar o registro de entidade de destino a vários registros de entidade relacionados em uma única operação, a operação de desassociação só pode desassociar um registro de entidade do registro de entidade de destino em cada operação.
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
});