# vyung.api.doc

**Repository Path**: suojj_admin/vyung.api.doc

## Basic Information

- **Project Name**: vyung.api.doc
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2020-02-17
- **Last Updated**: 2021-09-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 
支持online和本地部署

## 内容
* [请求例子](#请求例子)
  * [创建记录](#创建记录)
  * [更新记录](#更新记录)
  * [更新一个属性值](#更新一个属性的值)
  * [Upsert记录](#Upsert记录)
  * [删除记录](#删除记录)
    * [删除一个属性的值](#删除一个属性的值)
  * [查询单条记录](#查询单条记录)
  * [查询多条记录](#查询多条记录)
    
    * [查找所有记录](#查找所有记录)
  * [数量](#数量)
    * [Count limitation workaround](#count-limitation-workaround)
  * [关联记录](#关联记录)
  * [关联记录用单一导航属性](#关联记录用单一导航属性)
  * [解除关联](#解除关联)
  * [解除关联用单一属性导航](#解除关联用单一属性导航)
  * [fetxml查询](#fetxml查询)
    * [分页](#分页)
    * [Fetch查询所有记录](#Fetch查询所有记录)
  * [执行Web API functions](#执行Web-API-functions)
  * [执行 Web API actions](#执行Web-API-actions)

* [使用外键](#使用外键)
* [使用实体逻辑名称请求](#使用实体逻辑名称请求)

## 开始

### vyDynamicswebapi作为Dynamics 365 web resource

### npm使用
npm install vy-dynamics-webapi --save


var DynamicsWebApi = require('vy-dynamics-webapi');
```js

var dynamicsWebApi = new vyDynamicswebapi();

dynamicsWebApi.executeUnboundFunction("WhoAmI").then(function (response) {
   
}).catch(function(error){
    console.log(error.message);
});
```


### 配置

#### Web browser

```js
var dynamicsWebApi = new vyDynamicswebapi({ webApiVersion: '9.0' });

```


#### 配置参数
属性名称 | 类型 | 描述
------------ | ------------- | -------------
impersonate | String | 代理用户的Guid.
timeout | Number | 超时时间.
useEntityNames | Boolean |  在请求期间是否使用实体逻辑名称而不是集合逻辑名称
webApiUrl | String | https://myorg.api.crm.dynamics.com/api/data/v8.2/.
webApiVersion | String | 版本号，默认为8.0
axiosService | Object | axios对象，可以实现路由拦截等功能
作为外部系统调用时，第一次请求时会获取所有实体的元素据，作为web资源不会发生。

## 请求例子




注意：如果是请求url过长会自动变成批量请求

### 创建记录

```js
//初始化对象
var lead = {
    subject: "Test WebAPI",
    firstname: "Test",
    lastname: "WebAPI",
    jobtitle: "Title"
};
//调用创建方法
dynamicsWebApi.create(lead, "leads").then(function (id) {
   
}).catch(function (error) {
    
})
```

如果你需要你刚才创建的记录的其他字段

```js
//初始化对象
var lead = {
    subject: "Test WebAPI",
    firstname: "Test",
    lastname: "WebAPI",
    jobtitle: "Title"
};
//调用创建方法
dynamicsWebApi.create(lead, "leads", ["return=representation"]).then(function (record) {
   
	var subject = record.subject;
}).catch(function (error) {
    
})
```

当然你也可以添加一些字段的说明

```js
dynamicsWebApi.create(lead, "leads", ["return=representation", "odata.include-annotations=*"]) //...
//或者
dynamicsWebApi.create(lead, "leads", "return=representation,odata.include-annotations=*") //...
//如果想获取某些字段
dynamicsWebApi.create(lead, "leads", ["return=representation", "odata.include-annotations=*"], ["subject"]) //...
```

#### 高级请求

```js
//初始化对象
var lead = {
    subject: "Test WebAPI",
    firstname: "Test",
    lastname: "WebAPI",
    jobtitle: "Title"
};

var request = {
    collection: "leads",
    entity: lead,
    returnRepresentation: true
}

//调用方法
dynamicsWebApi.createRequest(request).then(function (record) {
	var subject = record.subject;
}).catch(function (error) {
    
})
```

### 更新记录

#### 基本

```js
//潜在客户的id
var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';

//初始化对象
//初始化需要更新的字段
var lead = {
    subject: "Test update",
    jobtitle: "Developer"
}
//调用更方法
dynamicsWebApi.update(leadId, "leads", lead).then(function () {
    
})
.catch(function (error) {
   
});
```

#### 高级

```js
var request = {
    key: '7d577253-3ef0-4a0a-bb7f-8335c2596e70',
    collection: "leads",
    entity: {
        subject: "Test update",
        jobtitle: "Developer"
    },
    returnRepresentation: true,
    select: ["fullname"]
};

dynamicsWebApi.updateRequest(request).then(function (response) {
    var fullname = response.fullname;
    
})
.catch(function (error) {
    
});
```

### 更新一个属性的值

```js
//潜在客户的id
var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';

//初始化键值对
var keyValuePair = { subject: "Update Single" };

//调用方法
dynamicsWebApi.updateSingleProperty(leadId, "leads", keyValuePair).then(function () {

})
.catch(function (error) {

});
```

### Upsert记录

#### 基本

```js

var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';

var lead = {
    subject: "Test Upsert"
};

//初始化对象

dynamicsWebApi.upsert(leadId, "leads", lead).then(function (id) {
    
})
.catch(function (error) {
   
});
```

#### 高级

```js
var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';

var request = {
    key: leadId,
    collection: "leads",
    returnRepresentation: true,
    select: ["fullname"],
    entity: {
        subject: "Test upsert"
    },
    ifnonematch: "*" //阻止更新
};

dynamicsWebApi.upsertRequest(request).then(function (record) {
    if (record != null) {
        //创建完成
    }
    else {
        //阻止更新
    }
})
.catch(function (error) {
    
});
```

### 删除记录

#### Basic

```js

var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';


dynamicsWebApi.deleteRecord(leadId, "leads").then(function () {
   
})
.catch(function (error) {
   
});
```

#### 高级

```js
//乐观并发删除
var request = {
    key: recordId,
    collection: "leads",
    ifmatch: 'W/"470867"'
}

dynamicsWebApi.deleteRequest(request).then(function (isDeleted) {
    if (isDeleted){
        //如果记录已经删除
    }
    else{
        //如果记录没有删除
    }
})
.catch(function (error) {
    
});
```

#### 删除一个属性的值

```js

var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';


dynamicsWebApi.deleteRecord(leadId, "leads", "subject").then(function () {
    
})
.catch(function (error) {
    
});
```

### 查询单条记录

#### 基本

```js
var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';


dynamicsWebApi.retrieve(leadid, "leads", ["fullname", "subject"]).then(function (record) {
    
})
.catch(function (error) {
   
});
```

#### 高级

```js
var request = {
    key: '7d577253-3ef0-4a0a-bb7f-8335c2596e70',
    collection: "leads",
    select: ["fullname", "subject"],

   
    ifnonematch: 'W/"468026"',

    
    includeAnnotations: "OData.Community.Display.V1.FormattedValue"
};

dynamicsWebApi.retrieveRequest(request).then(function (record) {
   
})
.catch(function (error) {
   
});
```

#### 查找关联实体使用单一值导航属性

基础和高级的都可以使用: `select: ["ownerid/$ref"]`.[单一值导航属性](https://docs.microsoft.com/zh-cn/previous-versions/dynamicscrm-2016/developers-guide/mt607871(v=crm.8)) 

```js
var leadId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';


dynamicsWebApi.retrieve(leadid, "leads", ["ownerid/$ref"]).then(function (reference) {
    var ownerId = reference.id;
    var collectionName = reference.collection; // systemusers or teams
}) 
```

#### 查找关联实体数据使用单一值导航属性

[single-valued navigation property](https://msdn.microsoft.com/en-us/library/mt607990.aspx#Anchor_5) 
关联实体属性名称前面必须加/,并且必须放到数组第一位

```js
var recordId = '7d577253-3ef0-4a0a-bb7f-8335c2596e70';


dynamicsWebApi.retrieve(recordId, "new_tests", ["/new_ParentLead", "fullname", "subject"])
    .then(function (leadRecord) {
        var fullname = leadRecord.fullname;
        
    }) 
```

高级方法使用 navigationProperty属性 或者和基本方法使用一样

```js
var request = {
    key: recordId,
    collection: "new_tests",
    navigationProperty: "new_ParentLead", //use request.navigationProperty
    select: ["fullname", "subject"]
}

//or

request = {
    key: recordId,
    collection: "new_tests",
    select: ["/new_ParentLead", "fullname", "subject"]    //inline with prefix "/"
}

dynamicsWebApi.retrieveRequest(request).then(function (leadRecord) {
    var fullname = leadRecord.fullname;
    
}) 
```

### 查询多条记录

#### 基本

```js
dynamicsWebApi.retrieveMultiple("leads", ["fullname", "subject"], "statecode eq 0").then(function (records) {
    
})
.catch(function (error) {
   
});
```

#### 高级
如果是lookup字段需要注意使用_`字段名称`_value的格式
```js

var request = {
    collection: "leads",
    select: ["fullname", "subject"],
    filter: "statecode eq 0",
    maxPageSize: 5,
    count: true
};


dynamicsWebApi.retrieveMultipleRequest(request).then(function (response) {

    var count = response.oDataCount;
    var nextLink = response.oDataNextLink;
    var records = response.value;
   
})
.catch(function (error){
   
});
```

##### 分页
```js

var request = {
    collection: "leads",
    select: ["fullname", "subject"],
    filter: "statecode eq 0",
    maxPageSize: 5,
    count: true
};


dynamicsWebApi.retrieveMultipleRequest(request).then(function (response) {
 
    var count = response.oDataCount;
    var nextLink = response.oDataNextLink;

    var records = response.value;
    dynamicsWebApi.retrieveMultipleRequest(request,nextLink).then(function (response) {
   
        var count = response.oDataCount;
        var nextLink = response.oDataNextLink;
        var records = response.value;

    })
.catch(function (error){
   
});

})
.catch(function (error){
   
});
```


#### 查找所有记录

基本

```js

dynamicsWebApi.retrieveAll("leads", ["fullname", "subject"], "statecode eq 0").then(function (response) {
    var records = response.value;
    
})
.catch(function (error){
   
});
```

高级

```js

var request = {
    collection: "leads",
    select: ["fullname", "subject"],
    filter: "statecode eq 0",
    maxPageSize: 5				
};


dynamicsWebApi.retrieveAllRequest(request).then(function (response) {

    var records = response.value;
  
})
.catch(function (error){
   
});
```

### 数量





这种解决方法的缺点是，它不仅返回计数数字，而且还返回集合中记录的所有数据。为了做一个小的
优化我添加了第三个参数到函数中，可以用来减少响应的长度。第三个参数表示选择查询选项
```js
dynamicsWebApi.countAll("leads", "statecode eq 0", ["subject"]).then(function (count) {
    
})
.catch(function (error) {
    
});
```



### 关联记录

```js
var accountId = '00000000-0000-0000-0000-000000000001';
var leadId = '00000000-0000-0000-0000-000000000002';
dynamicsWebApi.associate("accounts", accountId, "lead_parent_account", "leads", leadId).then(function () {
    
}).catch(function (error) {
    
});
```

### 关联记录用单一导航属性 

单一盗汗属性可以通过`GET` 请求加上header信息`Prefer:odata.include-annotations=Microsoft.Dynamics.CRM.associatednavigationproperty`, 
返回的记录的属性会包含`@Microsoft.Dynamics.CRM.associatednavigationproperty` 就是我们需要的单一导航的属性
通常我们可以用实体的字段的架构名称

例子

```js
var new_testid = '00000000-0000-0000-0000-000000000001';
var leadId = '00000000-0000-0000-0000-000000000002';
dynamicsWebApi.associateSingleValued("new_tests", new_testid, "new_ParentLead", "leads", leadId)
    .then(function () {
        
    }).catch(function (error) {
       
    });
```

### 解除关联

```js
var accountId = '00000000-0000-0000-0000-000000000001';
var leadId = '00000000-0000-0000-0000-000000000002';
dynamicsWebApi.disassociate("accounts", accountId, "lead_parent_account", leadId).then(function () {
    
}).catch(function (error) {
   
});
```

### 解除关联用单一属性导航
 [Associate for a single-valued navigation property](#associate-for-a-single-valued-navigation-property).

```js
var new_testid = '00000000-0000-0000-0000-000000000001';
dynamicsWebApi.disassociateSingleValued("new_tests", new_testid, "new_ParentLead").then(function () {
    
}).catch(function (error) {
    
});
```

### fetxml查询

```js
//声明fetchxml
var fetchXml = '<fetch mapping="logical">' +
                    '<entity name="account">' +
                        '<attribute name="accountid"/>' +
                        '<attribute name="name"/>' +
                    '</entity>' +
               '</fetch>';

dynamicsWebApi.executeFetchXml("accounts", fetchXml).then(function (response) {
   
})
.catch(function (error) {
   
});
```
`dynamicsWebApi.fetch(...)` 一样类似 `executeFetchXml`.

#### 分页

```js
//声明fetchxml
var fetchXml = '<fetch mapping="logical">' +
                    '<entity name="account">' +
                        '<attribute name="accountid"/>' +
                        '<attribute name="name"/>' +
                    '</entity>' +
               '</fetch>';

dynamicsWebApi.executeFetchXml("accounts", fetchXml).then(function (response) {
   

    return dynamicsWebApi
        .executeFetchXml("accounts", fetchXml, null, response.PagingInfo.nextPage, response.PagingInfo.cookie);
}).then(function (response) {
   

    return dynamicsWebApi
        .executeFetchXml("accounts", fetchXml, null, response.PagingInfo.nextPage, response.PagingInfo.cookie);
}).then(function (response) {
    
})

```

#### Fetch查询所有记录

获取全部的记录

```js
var fetchXml = '<fetch mapping="logical">' +
                    '<entity name="account">' +
                        '<attribute name="accountid"/>' +
                        '<attribute name="name"/>' +
                    '</entity>' +
               '</fetch>';

dynamicsWebApi.executeFetchXmlAll("accounts", fetchXml).then(function (response) {
    
   
})

```

`dynamicsWebApi.fetchAll(...)`一样类似`executeFetchXmlAll`.

### 执行Web API functions
[function列表](https://docs.microsoft.com/zh-cn/dynamics365/customer-engagement/web-api/functions?view=dynamics-ce-odata-9) 
#### Bound functions

```js
var teamId = "00000000-0000-0000-0000-000000000001";
dynamicsWebApi.executeBoundFunction(teamId, "teams", "Microsoft.Dynamics.CRM.RetrieveTeamPrivileges")
    .then(function (response) {
        
    }).catch(function (error) {
        
    });
```

#### Unbound functions

```js
var parameters = {
    LocalizedStandardName: 'Pacific Standard Time',
    LocaleId: 1033
};
dynamicsWebApi.executeUnboundFunction("GetTimeZoneCodeByLocalizedName", parameters).then(function (result) {
    var timeZoneCode = result.TimeZoneCode;
}).catch(function (error) {
    
});
```

### 执行Web API actions

#### Bound actions
[系统标准action列表](https://docs.microsoft.com/zh-cn/dynamics365/customer-engagement/web-api/actions?view=dynamics-ce-odata-9)
```js
var queueId = "00000000-0000-0000-0000-000000000001";
var letterActivityId = "00000000-0000-0000-0000-000000000002";
var actionRequest = {
    Target: {
        activityid: letterActivityId,
        "@odata.type": "Microsoft.Dynamics.CRM.letter"
    }
};
dynamicsWebApi.executeBoundAction(queueId, "queues", "Microsoft.Dynamics.CRM.AddToQueue", actionRequest)
    .then(function (result) {
        var queueItemId = result.QueueItemId;
    })
    .catch(function (error) {
        
    });
```

#### Unbound actions

```js
var opportunityId = "b3828ac8-917a-e511-80d2-00155d2a68d2";
var actionRequest = {
    Status: 3,
    OpportunityClose: {
        subject: "Won Opportunity",

       
        "opportunityid@odata.bind": "opportunities(" + opportunityId + ")"
    }
};
dynamicsWebApi.executeUnboundAction("WinOpportunity", actionRequest).then(function () {
   
}).catch(function (error) {
   
});
```


#### 限制

[Execute batch operations using the Web API](https://docs.microsoft.com/en-us/dynamics365/customer-engagement/developer/webapi/execute-batch-operations-using-web-api).

## 格式化值和lookup字段


For example:

```js



var doNotPostEmailFormatted = response.donotpostalmail_Formatted;



var customerName = response._customerid_value_Formatted;
var customerEntityLogicalName = response._customerid_value_LogicalName; 
var customerNavigationProperty = response._customerid_value_NavigationProperty;
```





OData Annotation | Property Suffix
------------ | -------------
`@OData.Community.Display.V1.FormattedValue` | `_Formatted`
`@Microsoft.Dynamics.CRM.lookuplogicalname` | `_LogicalName`
`@Microsoft.Dynamics.CRM.associatednavigationproperty` | `_NavigationProperty`

## 使用外键
使用外键可以增删改查 [More Info](https://msdn.microsoft.com/en-us/library/mt607871.aspx#Retrieve%20using%20an%20alternate%20key)

### Basic usage

```js
var alternateKey = "key='keyValue'"; 
//or var alternateKey = "key='keyValue',anotherKey='keyValue2'";

//执行查询操作
dynamicsWebApi.retrieve(alternateKey, "leads", ["fullname", "subject"]).then(function (record) {
  
})
.catch(function (error) {
   
});
```

###  高级请求对象

```js
var request = {
    key: "alternateKey='keyValue'",
    collection: 'leads',
    select: ['fullname', 'subject']
};

dynamicsWebApi.retrieveRequest(request).then(function (record) {
  
})
.catch(function (error) {
    
});
```


```js
var request = {
    key: '00000000-0000-0000-0000-000000000001',
    collection: 'leads',
    select: ['fullname', 'subject']
};

dynamicsWebApi.retrieveRequest(request).then(function (record) {
   
})
.catch(function (error) {
    
});
```

## 使用实体逻辑名称请求


```js
var dynamicsWebApi = new vyDynamicswebapi({ useEntityNames: true });


dynamicsWebApi.retrieve(leadId, 'lead', ['fullname', 'subject']).then(function (record) {
   
})
.catch(function (error) {
   
});



var request = {
    collection: 'lead',
    key: leadId,
    select:  ['fullname', 'subject']
};

dynamicsWebApi.retrieveRequest(request).then(function (record) {
   
})
.catch(function (error) {
    
});
```



```js
var account = {
    name: 'account name',
   'primarycontactid@odata.bind': 'contact(00000000-0000-0000-0000-000000000001)'
}

dynamicsWebApi.create(account, 'account').then(function(accountId)){
   
}).catch(function (error) {
    
});
```



```js

var collectionName = dynamicsWebApi.utility.getCollectionName('account');
```