# 使用指南

## 共享环境的小程序操作步骤

1.开通，使用 `1.03.2009140` 或以上版本的开发者工具，进入云控制台，在 「更多」中选择「环境共享」，点击开通即开通环境共享能力。

![image-20201223111919694](https://res8.wxqcloud.qq.com.cn/wxdoc/8cf3d478-9061-4fe5-a39f-963522073a8a.png)

2.共享，开通成功后，即进入「环境共享」页面，点击「添加共享」，即可授权**同主体下**其他小程序/公众号使用当前小程序下的云开发资源。
![image-20201223112031435](https://res8.wxqcloud.qq.com.cn/wxdoc/c2d8546e-c9fd-4e8e-84ce-28cb6d44f52c.png)

![image-20201223112417833](https://res8.wxqcloud.qq.com.cn/wxdoc/740fab72-d3e4-4f9d-955c-4dc868615bea.png)

3.授权，输入 AppID 点击查询按钮，选择目标小程序/公众号对其进行授权，选择想要共享的云环境，默认选中该云环境下所有查看/操作权限，可根据实际使用场景自定义授权。**如需共享多个云环境，点击加号按钮选择云环境及权限即可。**
![image-20201223112518034](https://res8.wxqcloud.qq.com.cn/wxdoc/65d22b37-513e-43c9-8bc8-79c5a6214cdb.png)
注意：授权只可授权当前小程序的自有环境，如 A 有 B 授权的环境，A 不可将 B 授权的环境再次授权给 C；

4.cloudbase_auth 云函数，在使用共享环境之前，需要保证资源方拥有 `cloudbase_auth` 云函数，用于鉴权调用方的身份并制定相关权限。

在调用方 `cloud.init()` 的过程中，会**首先执行**这个函数，如果这个函数不存在，会提示找不到对应的`FunctionName`。请务必参考示例在资源方添加此函数。

被调的资源方小程序 cloudbase_auth 云函数简易示例：
```js
const cloud = require('wx-server-sdk')
cloud.init({
  env: cloud.DYNAMIC_CURRENT_ENV
})

// 云函数入口函数
exports.main = async (event, context) => {
  const wxContext = cloud.getWXContext()

  console.log(event)
  console.log(wxContext)
  // 跨账号调用时，由此拿到来源方小程序/公众号 AppID
  console.log(wxContext.FROM_APPID)
  // 跨账号调用时，由此拿到来源方小程序/公众号的用户 OpenID
  console.log(wxContext.FROM_OPENID)
  // 跨账号调用、且满足 unionid 获取条件时，由此拿到同主体下的用户 UnionID
  console.log(wxContext.FROM_UNIONID)

  return {
    errCode: 0,
    errMsg: '',
    auth: JSON.stringify({
      // 自定义安全规则
      // 在前端访问资源方数据库、云函数等资源时，资源方可以通过
      // 安全规则的 `auth.custom` 字段获取此对象的内容做校验，
      // 像这个示例就是资源方可以在安全规则中通过 `auth.custom.x` 获取
      x: 1,
    }),
  }
}
```

**cloudbase_auth 云函数交互协议说明**

`cloudbase_auth` 云函数返回的对象结构协议：

| 属性 | 类型 | 默认值 | 必填 | 说明 |
| ---- | ---- | ------ | -------- | ---- |
| errCode | number |  | 是 | 自定义错误码，0 表示授权通过，非 0 表示拒绝授权，会透传回给调用方 |
| errMsg | string |  | 否 | 自定义错误信息，errCode 非 0 时透传回给调用方 |
| auth | string |  | 否 | 安全规则对象，必须序列化成字符串 |

### 被共享环境的小程序使用步骤

1.查看，使用 `1.03.2009140` 或以上版本的开发者工具，进入云控制台，点击「更多-环境共享」进入「环境共享」页面可查看被共享小程序情况；
![image-20201223112757271](https://res8.wxqcloud.qq.com.cn/wxdoc/cc133b4d-dc39-439f-bb81-e7cf4f8d8275.png)

2.操作环境资源，如需在云控制台查看授权环境的资源情况，可前往「设置-环境名称」将环境切换至该授权环境即可，同时在被授权操作的情况下可以对授权环境进行操作。如添加云函数/云托管服务/数据库集合等操作；
![image-20201223112944134](https://res8.wxqcloud.qq.com.cn/wxdoc/1a01439a-6323-4be8-a5e9-4711d95e5239.png)

![image-20201223113031807](https://res8.wxqcloud.qq.com.cn/wxdoc/9bcdb678-f965-44c5-83cd-c5a2c6b53961.png)

3.调用共享环境资源，与在小程序中无多少区别。

小程序代码使用示例（需小程序公共库 `2.13.0` 或以上）：

```js
// 声明新的 cloud 实例
var c1 = new wx.cloud.Cloud({
  // 资源方 AppID
  resourceAppid: 'wxe0e2656d74f0bff3',
  // 资源方环境 ID
  resourceEnv: '环境ID',
})

// 跨账号调用，必须等待 init 完成
// init 过程中，资源方小程序对应环境下的 cloudbase_auth 函数会被调用，并需返回协议字段（见下）来确认允许访问、并可自定义安全规则
await c1.init()

// 完成后正常使用资源方的已授权的云资源
await c1.callFunction({
  name: '函数名',
  data: {},
})
```

### 环境共享下的云调用

跨账号环境共享时，云调用也是可以生效的，小程序 A 获得了小程序 B 的授权，那么比如在 A 小程序的云函数中也可以发起 B 的云调用。需注意的是，在 A 小程序的云函数里发起云调用时默认是以 A 的身份发起的，如果在环境共享的场景下需要以其他小程序的身份发起，需要指定 AppID。

示例代码：小程序 A 调用小程序 B 的云函数 b，然后在云函数 b 里面希望以小程序 A 的身份发起，则需在调用时指定：

```js
// 在小程序 B 的云函数 b 里处理来自 A 小程序的请求时，对 B 小程序的用户发送订阅消息：
cloud.openapi({ appid: 'A小程序AppID' }).subscribeMessage.send({ 
  touser: cloud.getWXContext().FROM_OPENID,
  // ...
})
```

### 其他操作

#### 环境权限配置

共享环境的小程序进入「环境共享」页面，我共享的小程序/公众号列表，点击「配置环境」，可对环境及环境的权限进行自定义设置；
![image-20201223113344952](https://res8.wxqcloud.qq.com.cn/wxdoc/b5260a4e-2927-4ccd-81d1-f6a4d109f0dc.png)

点击加号按钮，可共享多个环境；点击减号按钮，可解除某个环境的共享关系；

#### 解除共享关系

共享与被共享双方都可以单方面解除环境共享关系，进入「环境共享」页面，我共享的小程序/公众号、共享给我的小程序列表，选择目标小程序，点击「解除」，确定即可解除成功。
![image-20201223114136209](https://res8.wxqcloud.qq.com.cn/wxdoc/9be5108c-f39a-45aa-a145-a0201a7e9ef7.png)

![image-20201223114221713](https://res8.wxqcloud.qq.com.cn/wxdoc/65734cbd-dc58-4244-9c7f-8dceec66a44c.png)

注意：解除共享关系后，被共享的小程序/公众号将无法用任何方式调用当前小程序所有云开发资源，且使用当前小程序云资源的云服务也将不可用。

当前解除功能是小程序/公众号级别解除，单个环境的解除只有共享资源方有权限，共享资源方可前往「配置环境」中，选择目标环境，点击减号按钮，提交后即可解除成功。

共享环境的小程序单方面解除共享关系后，为避免出现未更换调用资源方资源而出现调用失败的情况，将发送「解除环境共享消息通知」给被共享环境的小程序/公众号管理员。

#### 注销环境共享

如不再需要环境共享功能，可前往「设置-拓展功能」中，选择环境共享进行注销，注销前需将所有共享关系解除。
![image-20201223111631559](https://res8.wxqcloud.qq.com.cn/wxdoc/62c5735b-6be8-4ca4-bba8-9532a81e474e.png)