From d50f1433605eb6584e59d7696ad2be174410164c Mon Sep 17 00:00:00 2001 From: wangyaqi Date: Fri, 17 Jan 2020 15:01:38 +0800 Subject: [PATCH] =?UTF-8?q?update:=20=E8=B0=83=E6=95=B4uniCloud=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/unicloud/_sidebar.md | 2 +- docs/unicloud/authentication.md | 96 ++++++++++++------- docs/unicloud/cf-authentication.md | 35 ++++++- docs/unicloud/cf-database.md | 8 ++ docs/unicloud/cf-functions.md | 11 +-- docs/unicloud/cf-storage.md | 148 ++++++++++++++--------------- 6 files changed, 179 insertions(+), 121 deletions(-) diff --git a/docs/unicloud/_sidebar.md b/docs/unicloud/_sidebar.md index fd72fc46b7..497af543a3 100644 --- a/docs/unicloud/_sidebar.md +++ b/docs/unicloud/_sidebar.md @@ -1,10 +1,10 @@ * [什么是uniCloud](uniCloud/README.md) * [快速上手](uniCloud/quickstart.md) * 服务端sdk - * [身份认证](uniCloud/cf-authentication.md) * [云函数](uniCloud/cf-functions.md) * [数据库](uniCloud/cf-database.md) * [云存储](uniCloud/cf-storage.md) + * [身份认证](uniCloud/cf-authentication.md) * 客户端sdk * [初始化](uniCloud/init.md) * [云函数](uniCloud/functions.md) diff --git a/docs/unicloud/authentication.md b/docs/unicloud/authentication.md index 72dd0e5834..78932d4d47 100644 --- a/docs/unicloud/authentication.md +++ b/docs/unicloud/authentication.md @@ -1,6 +1,10 @@ **本章内容仅针对腾讯云开发，阿里侧暂不支持** -## 获取登录对象 +**腾讯云侧必须以任意登录方式登录之后才可以访问云端资源。开发者在控制台开启匿名登录之后，可以在客户端调用匿名登录来获取访问云端资源的权限** + +## uniClient.auth() + +获取登录对象 **示例代码** @@ -9,13 +13,12 @@ const uniClient = uniCloud.init({ spaceId: 'xxxx-yyy' }); -let auth = uniClient.auth() +const auth = uniClient.auth() ``` +## auth.signInAnonymously() -## 获取登录状态 - -开发者可以通过 `getLoginState()` 来获取当前的登录状态，调用 `getLoginState()` 后，SDK 会识别本地是否有登录状态，如果有，则会尝试刷新登录状态，若刷新登录状态成功，则会返回新的登录状态，否则返回 `undefined`。 +进行匿名登录，详细描述参考[匿名登录](#匿名登录) **示例代码** @@ -23,7 +26,35 @@ let auth = uniClient.auth() const uniClient = uniCloud.init({ spaceId: 'xxxx-yyy' }); -uniClient.auth().getLoginState().then(loginState => { + +const auth = uniClient.auth() +auth.signInAnonymously() +``` + +## auth.signInWithTicket() + +进行自定义登录，详细描述参考[自定义登录](#自定义登录) + +**示例代码** + +```js +auth.signInWithTicket('YourTicket').then(() => { + // 获取用户信息 + return auth.getUserInfo() + }) + .then(userInfo => { + //... + }) +``` + +## auth.getLoginState() + +开发者可以通过 `getLoginState()` 来获取当前的登录状态，调用 `getLoginState()` 后，SDK 会识别本地是否有登录状态，如果有，则会尝试刷新登录状态，若刷新登录状态成功，则会返回新的登录状态，否则返回 `undefined`。 + +**示例代码** + +```js +auth.getLoginState().then(loginState => { if (loginState) { // 登录态有效 } else { @@ -32,6 +63,29 @@ uniClient.auth().getLoginState().then(loginState => { }) ``` +## auth.getUserInfo() + +任何方式登录成功后，可以调用 `getUserInfo` 获得用户的身份信息。 + +**响应参数** + +|字段 |类型 |是否必备 |说明 | +|:-: |:-: |:-: |:-: | +|uid |string |是 |用户在云开发的唯一ID | + + +**示例代码** + +```js +auth.signInWithTicket('YourTicket').then(() => { + // 获取用户信息 + return auth.getUserInfo() + }) + .then(userInfo => { + //... + }) +``` + ## 自定义登录 `uniCloud`允许开发者使用特定的登录凭据`Ticket`对用户进行身份认证。开发者可以使用`服务端 SDK`来创建`Ticket`，并且将`token`传入到应用内，然后调用`signInWithTicket()`获得登录态。 @@ -100,32 +154,6 @@ auth.signInWithTicket(ticket).then(() => { }) ``` -## 获取用户信息 - -任何方式登录成功后，可以调用 `getUserInfo` 获得用户的身份信息。 - -**响应参数** - -|字段 |类型 |是否必备 |说明 | -|:-: |:-: |:-: |:-: | -|uid |string |是 |用户在云开发的唯一ID | -|customUserId |string |否 |用户使用自定义登录传入的用户Id | - -**示例代码** -```js -const uniClient = uniCloud.init({ - spaceId: 'xxxx-yyy' -}); - -const auth = uniClient.auth() -auth.signInWithTicket('YourTicket').then(() => { - // 获取用户信息 - return auth.getUserInfo() - }) - .then(userInfo => { - //... - }) -``` ## 匿名登录 uniCloud允许开发者使用匿名登录的方式进行静默授权，可以避免强制登录。在匿名状态下可正常的调用uniCloud的资源，开发者同时可以配合安全规则针对匿名用户制定对应的访问限制。 @@ -137,10 +165,6 @@ uniCloud允许开发者使用匿名登录的方式进行静默授权，可以避 ### 客户端进行匿名登录 ```js -const uniClient = uniCloud.init({ - spaceId: 'xxxx-yyy' -}); -const auth = uniClient.auth(); await auth.signInAnonymously().catch(err=>{ // 登录失败会抛出错误 }); diff --git a/docs/unicloud/cf-authentication.md b/docs/unicloud/cf-authentication.md index be8a376fd0..9de7afc045 100644 --- a/docs/unicloud/cf-authentication.md +++ b/docs/unicloud/cf-authentication.md @@ -1,10 +1,16 @@ -## 获取 auth 的引用 +**本章内容仅针对腾讯云，阿里云暂不支持** + +### uniCloud.auth() + +获取`auth`的引用 ```js const auth = uniCloud.auth(); ``` -#### 获取用户信息 +### auth.getUserInfo() + +获取用户信息 ```js const { @@ -13,6 +19,29 @@ const { } = auth.getUserInfo() ``` -## 云函数生成登录凭证 +### auth.getClientIP() + +获取客户端IP地址 + +```js +const IP = auth.getClientIP() +``` + +### auth.createTicket(String customUserId, Object createTicketOptions) 开发者可以使用云函数创建登录凭证，提供给客户端进行登录操作。[详见](uniCloud/authentication.md#自定义登录) + +**createTicketOptions参数说明** + +|参数名 |类型 |必填 |默认值 |说明 |平台差异说明 | +|:- |:- |:- |:- |:- |:- | +|refresh|Number |否 |3600000|token刷新间隔|- | + +```js +let customUserId = '123456'; + +const ticket = auth.createTicket(customUserId, { + refresh: 10 * 60 * 1000 // 每十分钟刷新一次登录态， 默认为一小时 +}); +// 然后把 ticket 发送给客户端 +``` diff --git a/docs/unicloud/cf-database.md b/docs/unicloud/cf-database.md index d66321420b..32f0140228 100644 --- a/docs/unicloud/cf-database.md +++ b/docs/unicloud/cf-database.md @@ -4,6 +4,14 @@ const db = uniCloud.database(); ``` +## 新增集合 + +如果集合已存在，则报错。 + +``` +db.createCollection(collectionName) +``` + ## 获取集合的引用 ```js diff --git a/docs/unicloud/cf-functions.md b/docs/unicloud/cf-functions.md index 2c28534ffa..8b305aac06 100644 --- a/docs/unicloud/cf-functions.md +++ b/docs/unicloud/cf-functions.md @@ -1,9 +1,8 @@ -## 执行函数 +## uniCloud.callFunction(Object callFunctionOptions) -- 接口名称：callFunction(object) -- 接口功能：远程调用云函数。 +云函数中调用云函数。**目前仅腾讯云支持** -### 请求参数 +**callFunctionOptions参数说明** | 字段 | 类型 | 必填| 说明 | | --- | --- | --- | --- | @@ -11,7 +10,7 @@ | data | object | 否 | 云函数参数。| | callback| function| 否 | 回调函数。 | -### 响应参数 +**响应参数** | 字段 | 类型 | 必填| 说明 | | --- | --- | --- | --- | @@ -20,7 +19,7 @@ | result | object| 否 | 云函数执行结果。 | | requestId | string| 否 | 请求序列号，用于错误排查。| -### 示例代码 +**示例代码** ```javascript //promise diff --git a/docs/unicloud/cf-storage.md b/docs/unicloud/cf-storage.md index d64b01c694..bcdcaeb43e 100644 --- a/docs/unicloud/cf-storage.md +++ b/docs/unicloud/cf-storage.md @@ -1,25 +1,24 @@ -## 上传文件 -- 接口名称： uploadFile -- 接口功能：上传文件至云开发存储服务。 -- 阿里云暂不支持此接口 +## uniCloud.uploadFile(Object uploadFileOptions) -### 请求参数 +上传文件至云开发存储服务。**目前仅腾讯云支持此接口** -| 字段 | 类型 | 必填 | 说明| -| --- | --- | --- | --- | -| cloudPath | string | 是 | 文件的绝对路径，包含文件名。例如 foo/bar.jpg、foo/bar/baz.jpg 等。[查看详情](https://cloud.tencent.com/document/product/436/13324) 。 | -| fileContent | fs.ReadStream | 是 | buffer或要上传的文件 [可读流](https://nodejs.org/api/stream.html#stream_class_stream_readable) 。| +**uploadFileOptions参数说明** -### 响应参数 +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| cloudPath | string | 是 | 文件的绝对路径，包含文件名。例如 foo/bar.jpg、foo/bar/baz.jpg 等。 | +| fileContent | fs.ReadStream | 是 | buffer或要上传的文件 [可读流](https://nodejs.org/api/stream.html#stream_class_stream_readable) 。 | -| 字段 | 类型 | 必填 | 说明| -| --- | --- | --- | --- | -| code | string | 否 | 状态码，操作成功则不返回。 | -| message | string | 否 | 错误描述。 | -| fileID | fileID | 是 | 文件唯一 ID，用来访问文件，建议存储起来。 | -| requestId | string | 否 | 请求序列号，用于错误排查。 | +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | string| 否 | 状态码，操作成功则不返回。 | +| message | string| 否 | 错误描述。 | +| fileID | fileID| 是 | 文件唯一 ID，用来访问文件，建议存储起来。 | +| requestId | string| 否 | 请求序列号，用于错误排查。 | -### 示例代码 +**示例代码** ```javascript const fs = require("fs"); @@ -30,41 +29,41 @@ let result = await uniCloud.uploadFile({ }); ``` -## 获取文件下载链接 -- 接口名称：getTempFileURL -- 接口功能：获取已上传至云开发的文件的访问链接。 +## uniCloud.getTempFileURL(Object getTempFileURLOptions) -### 请求参数 +获取文件下载链接，**目前仅腾讯云支持** -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| fileList | <Array>.string | 是 | 要下载的文件 ID 组成的数组。 | +**getTempFileURLOptions参数说明** -fileList +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| fileList| <Array>.string| 是 | 要下载的文件 ID 组成的数组。| -| 字段 | 类型 | 必填 | 说明 -| --- | --- | --- | --- | -| fileID | string | 是 | 文件 ID。 | -| maxAge | Integer | 是 | 文件链接有效期。 | +**fileList字段** -### 响应参数 +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| fileID| string | 是 | 文件 ID。 | +| maxAge| Integer | 是 | 文件链接有效期。| -| 字段 | 类型 | 必填 | 说明 -| --- | --- | --- | --- | -| code | string | 否 | 状态码，操作成功则为 SUCCESS。 | -| message | string | 否 | 错误描述。 | -| fileList | <Array>.object | 否 | 存储下载链接的数组。 | -| requestId | string | 否 | 请求序列号，用于错误排查。 | +**响应参数** -fileList +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | string | 否 | 状态码，操作成功则为 SUCCESS。| +| message | string | 否 | 错误描述。 | +| fileList | <Array>.object| 否 | 存储下载链接的数组。 | +| requestId | string | 否 | 请求序列号，用于错误排查。 | -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| code | string | 否 | 删除结果，成功为 SUCCESS。 | -| fileID | string | 是 | 文件 ID。 | -| tempFileURL | string | 是 | 文件访问链接。 | +**fileList字段** -### 示例代码 +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | string| 否 | 删除结果，成功为 SUCCESS。| +| fileID | string| 是 | 文件 ID。 | +| tempFileURL | string| 是 | 文件访问链接。 | + +**示例代码** ```javascript let result = await uniCloud.getTempFileURL({ @@ -72,34 +71,33 @@ let result = await uniCloud.getTempFileURL({ }); ``` -## 删除文件 +## uniCloud.deleteFile(Object deleteFileOptions) -接口名称：deleteFile -接口功能：删除云端文件。 +删除云端文件。 -### 请求参数 +**deleteFileOptions参数说明** -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| fileList | <Array>.string | 是 | 要删除的文件 ID 组成的数组。 | +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| fileList| <Array>.string| 是 | 要删除的文件 ID 组成的数组。| -### 响应参数 +**响应参数** -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| code | string | 否 | 状态码，操作成功则不返回。 | -| message | string | 否 | 错误描述 | -| fileList | <Array>.object | 否 | 删除结果组成的数组。 | -| requestId | string | 否 | 请求序列号，用于错误排查。 | +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | string | 否 | 状态码，操作成功则不返回。| +| message | string | 否 | 错误描述 | +| fileList | <Array>.object| 否 | 删除结果组成的数组。 | +| requestId | string | 否 | 请求序列号，用于错误排查。| -fileList +**fileList字段** | 字段 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | code | string | 否 | 删除结果，成功为SUCCESS。 | | fileID | string | 是 | 文件 ID。 | -### 示例代码 +**示例代码** ```javascript let result = await uniCloud.deleteFile({ @@ -109,27 +107,27 @@ let result = await uniCloud.deleteFile({ }); ``` -## 下载文件 -- 接口名称：downloadFile -- 接口功能：下载已上传至云开发的文件至本地（默认本地根目录/root）。 +## uniCloud.downloadFile(Object downloadFileOptions) -### 请求参数 +下载已上传至云开发的文件至本地（默认本地根目录/root）。 -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| fileID | string | 是 | 要下载的文件的 ID。 | -| tempFilePath | string | 否 | 下载的文件要存储的位置。 | +**downloadFileOptions参数说明** -### 响应参数 +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| fileID | string| 是 | 要下载的文件的 ID。 | +| tempFilePath| string| 否 | 下载的文件要存储的位置。| -| 字段 | 类型 | 必填 | 说明 | -| --- | --- | --- | --- | -| code | string | 否 | 状态码，操作成功则不返回。 | -| message | string | 否 | 错误描述。 | -| fileContent | Buffer | 否 | 下载的文件的内容。如果传入 tempFilePath 则不返回该字段。 | -| requestId | string | 否 | 请求序列号，用于错误排查。 | +**响应参数** + +| 字段 | 类型 | 必填| 说明 | +| --- | --- | --- | --- | +| code | string| 否 | 状态码，操作成功则不返回。 | +| message | string| 否 | 错误描述。 | +| fileContent | Buffer| 否 | 下载的文件的内容。如果传入 tempFilePath 则不返回该字段。| +| requestId | string| 否 | 请求序列号，用于错误排查。 | -### 示例代码 +**示例代码** ```javascript let result = await uniCloud.downloadFile({ -- GitLab