Browse Source

First commit.

master
YJC 1 year ago
commit
2b812c5339
70 changed files with 3203 additions and 0 deletions
  1. +2
    -0
      .dockerignore
  2. +10
    -0
      Dockerfile
  3. +18
    -0
      docker-compose.yml
  4. +41
    -0
      docs/README.md
  5. +29
    -0
      docs/SUMMARY.md
  6. +19
    -0
      docs/alicloud_batch_compute/0.概述.md
  7. +29
    -0
      docs/alicloud_batch_compute/1.批量计算架构.md
  8. +48
    -0
      docs/alicloud_batch_compute/2.功能特性.md
  9. +37
    -0
      docs/alicloud_batch_compute/3.名词解释.md
  10. +43
    -0
      docs/alicloud_batch_compute/4.准备工作.md
  11. +37
    -0
      docs/alicloud_batch_compute/5.支持地域.md
  12. +43
    -0
      docs/alicloud_oss/0.什么是对象存储.md
  13. +67
    -0
      docs/alicloud_oss/1.存储类型介绍.md
  14. +107
    -0
      docs/alicloud_oss/2.访问域名和数据中心.md
  15. +102
    -0
      docs/alicloud_oss/3.OSS访问域名使用规则.md
  16. +39
    -0
      docs/alicloud_oss/4.功能概览.md
  17. +128
    -0
      docs/alicloud_oss/5.基本概念介绍.md
  18. +71
    -0
      docs/alicloud_oss/6.存储类型转换.md
  19. +109
    -0
      docs/alicloud_oss/7.创建和使用归档存储类型.md
  20. +6
    -0
      docs/book.json
  21. +7
    -0
      docs/choppy-docs.code-workspace
  22. +121
    -0
      docs/choppy_app/0.概要.md
  23. +18
    -0
      docs/choppy_app/1.变量.md
  24. +141
    -0
      docs/choppy_app/2.表达式.md
  25. +69
    -0
      docs/choppy_app/3.过滤器.md
  26. +41
    -0
      docs/choppy_app/4.空白控制.md
  27. +39
    -0
      docs/choppy_app/5.控制结构.md
  28. +23
    -0
      docs/choppy_app/6.注释.md
  29. +34
    -0
      docs/choppy简介.md
  30. BIN
      docs/images/choppy.png
  31. BIN
      docs/images/choppy_ppt_1.png
  32. BIN
      docs/images/choppy_ppt_10.png
  33. BIN
      docs/images/choppy_ppt_11.png
  34. BIN
      docs/images/choppy_ppt_12.png
  35. BIN
      docs/images/choppy_ppt_13.png
  36. BIN
      docs/images/choppy_ppt_14.png
  37. BIN
      docs/images/choppy_ppt_2.png
  38. BIN
      docs/images/choppy_ppt_3.png
  39. BIN
      docs/images/choppy_ppt_4.png
  40. BIN
      docs/images/choppy_ppt_5.png
  41. BIN
      docs/images/choppy_ppt_6.png
  42. BIN
      docs/images/choppy_ppt_7.png
  43. BIN
      docs/images/choppy_ppt_8.png
  44. BIN
      docs/images/choppy_ppt_9.png
  45. +321
    -0
      docs/quick_introduction.md
  46. +262
    -0
      docs/style/website.css
  47. +92
    -0
      docs/wdl/0.WDL快速入门.md
  48. +5
    -0
      package.json
  49. +193
    -0
      website/README.md
  50. +18
    -0
      website/blog/2016-03-11-blog-post.md
  51. +18
    -0
      website/blog/2017-04-10-blog-post-two.md
  52. +11
    -0
      website/blog/2017-09-25-testing-rss.md
  53. +10
    -0
      website/blog/2017-09-26-adding-rss.md
  54. +8
    -0
      website/blog/2017-10-24-new-version-1.0.0.md
  55. +100
    -0
      website/core/Footer.js
  56. +14
    -0
      website/package.json
  57. +52
    -0
      website/pages/en/help.js
  58. +196
    -0
      website/pages/en/index.js
  59. +48
    -0
      website/pages/en/users.js
  60. +36
    -0
      website/sidebars.json
  61. +114
    -0
      website/siteConfig.js
  62. +1
    -0
      website/static/choppy-docs-buttons.js
  63. +89
    -0
      website/static/css/custom.css
  64. BIN
      website/static/img/choppy.png
  65. BIN
      website/static/img/code.png
  66. BIN
      website/static/img/easy.png
  67. BIN
      website/static/img/platform.png
  68. BIN
      website/static/img/quartet-logo.png
  69. BIN
      website/static/img/reproducibility.png
  70. +137
    -0
      yarn.lock

+ 2
- 0
.dockerignore View File

@@ -0,0 +1,2 @@
*/node_modules
*.log

+ 10
- 0
Dockerfile View File

@@ -0,0 +1,10 @@
FROM node:8.11.4

WORKDIR /app/website

EXPOSE 3000 35729
COPY ./docs /app/docs
COPY ./website /app/website
RUN yarn install

CMD ["yarn", "start"]

+ 18
- 0
docker-compose.yml View File

@@ -0,0 +1,18 @@
version: "3"

services:
docusaurus:
image: registry-vpc.cn-shanghai.aliyuncs.com/pgx-docker-registry/choppy-docs:v0.1.0
ports:
- 3000:3000
- 35729:35729
volumes:
- /data/choppy-docs/docs:/app/docs
- /data/choppy-docs/website/blog:/app/website/blog
- /data/choppy-docs/website/core:/app/website/core
- /data/choppy-docs/website/i18n:/app/website/i18n
- /data/choppy-docs/website/pages:/app/website/pages
- /data/choppy-docs/website/static:/app/website/static
- /data/choppy-docs/website/sidebars.json:/app/website/sidebars.json
- /data/choppy-docs/website/siteConfig.js:/app/website/siteConfig.js
working_dir: /app/website

+ 41
- 0
docs/README.md View File

@@ -0,0 +1,41 @@
# 用户指南:Choppy for Reproducible Omics Pipeline

## Pipeline 分析三步走

基于`Choppy平台`进行 Pipeline 分析十分简单高效,只需要三步即可轻松搞定(**点击进入[演示视频](http://kancloud.nordata.cn/2019-01-20-choppy.mp4)**):

1. 登陆**[Choppy App Store](http://choppy.3steps.cn)**,挑选符合自己需求的 App,并安装
2. 准备 App 所需的 Samples 文件
3. 提交任务

## 文档大纲

- [Choppy 简介](choppy简介.md)
- [第一章 快速指南](./quick_introduction.md)
- [第二章 Cromwell](cromwell/toc.md)
- [第三章 WDL 定义](wdl/toc.md)
- [1.1 快速入门](wdl/0.WDL快速入门.md)
- [第四章 Choppy App 定义](choppy_app/toc.md)
- [1.1 概要](choppy_app/0.概要.md)
- [1.2 模板变量](choppy_app/1.变量.md)
- [1.3 模板表达式](choppy_app/2.表达式.md)
- [1.4 模板过滤器](choppy_app/3.过滤器.md)
- [1.5 模板空白控制](choppy_app/4.空白控制.md)
- [1.6 模板控制结构](choppy_app/5.控制结构.md)
- [1.7 模板注释](choppy_app/6.模板注释.md)
- [第五章 阿里云批量计算](alicloud_batch_compute/toc.md)
- [1.1 概述](alicloud_batch_compute/0.概述.md)
- [1.2 批量计算框架](alicloud_batch_compute/1.批量计算框架.md)
- [1.3 功能特性](alicloud_batch_compute/2.功能特性.md)
- [1.4 名词解释](alicloud_batch_compute/3.名词解释.md)
- [1.5 准备工作](alicloud_batch_compute/4.准备工作.md)
- [1.6 支持地域](alicloud_batch_compute/5.支持地域.md)
- [第六章 阿里云 OSS 存储](alicloud_oss/toc.md)
- [1.1 什么是对象存储](alicloud_oss/0.什么是对象存储.md)
- [1.2 存储类型介绍](alicloud_oss/1.存储类型介绍.md)
- [1.3 访问域名和数据中心](alicloud_oss/2.访问域名和数据中心.md)
- [1.4 OSS 访问域名使用规则](alicloud_oss/3.OSS访问域名使用规则.md)
- [1.5 功能概览](alicloud_oss/4.功能概览.md)
- [1.6 基本概念介绍](alicloud_oss/5.基本概念介绍.md)
- [1.7 存储类型转换](alicloud_oss/6.存储类型转换.md)
- [1.8 创建和使用归档存储类型](alicloud_oss/7.创建和使用归档存储类型.md)

+ 29
- 0
docs/SUMMARY.md View File

@@ -0,0 +1,29 @@
- [Choppy 简介](choppy简介.md)
- [第一章 快速指南](./quick_introduction.md)
- [第二章 Cromwell](cromwell/toc.md)
- [第三章 WDL 定义](wdl/toc.md)
- [1.1 快速入门](wdl/0.WDL快速入门.md)
- [第四章 Choppy App 定义](choppy_app/toc.md)
- [1.1 概要](choppy_app/0.概要.md)
- [1.2 模板变量](choppy_app/1.变量.md)
- [1.3 模板表达式](choppy_app/2.表达式.md)
- [1.4 模板过滤器](choppy_app/3.过滤器.md)
- [1.5 模板空白控制](choppy_app/4.空白控制.md)
- [1.6 模板控制结构](choppy_app/5.控制结构.md)
- [1.7 模板注释](choppy_app/6.模板注释.md)
- [第五章 阿里云批量计算](alicloud_batch_compute/toc.md)
- [1.1 概述](alicloud_batch_compute/0.概述.md)
- [1.2 批量计算框架](alicloud_batch_compute/1.批量计算框架.md)
- [1.3 功能特性](alicloud_batch_compute/2.功能特性.md)
- [1.4 名词解释](alicloud_batch_compute/3.名词解释.md)
- [1.5 准备工作](alicloud_batch_compute/4.准备工作.md)
- [1.6 支持地域](alicloud_batch_compute/5.支持地域.md)
- [第六章 阿里云 OSS 存储](alicloud_oss/toc.md)
- [1.1 什么是对象存储](alicloud_oss/0.什么是对象存储.md)
- [1.2 存储类型介绍](alicloud_oss/1.存储类型介绍.md)
- [1.3 访问域名和数据中心](alicloud_oss/2.访问域名和数据中心.md)
- [1.4 OSS 访问域名使用规则](alicloud_oss/3.OSS访问域名使用规则.md)
- [1.5 功能概览](alicloud_oss/4.功能概览.md)
- [1.6 基本概念介绍](alicloud_oss/5.基本概念介绍.md)
- [1.7 存储类型转换](alicloud_oss/6.存储类型转换.md)
- [1.8 创建和使用归档存储类型](alicloud_oss/7.创建和使用归档存储类型.md)

+ 19
- 0
docs/alicloud_batch_compute/0.概述.md View File

@@ -0,0 +1,19 @@
---
id: bc-intro
title: 什么是批量计算
sidebar_label: 什么是批量计算
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 什么是批量计算

批量计算(BatchCompute)是一种适用于大规模并行批处理作业的分布式云服务。BatchCompute 可支持海量作业并发规模,系统自动完成资源管理、作业调度和数据加载,并按实际使用量计费。

通俗的讲,就是您可以提交一个任意的计算机程序,让它在阿里云的多个 VM 实例上同时运行,然后把结果写入到指定的持久化存储位置(如阿里云对象存储 OSS 或者文件存储 NAS),然后您可以去指定的位置查看结果。

![批量计算](http://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/pic/27994/cn_zh/1524795335543/10_14_18__04_27_2018.jpg)

+ 29
- 0
docs/alicloud_batch_compute/1.批量计算架构.md View File

@@ -0,0 +1,29 @@
---
id: bc-framework
title: BatchCompute 整体架构
sidebar_label: BatchCompute 整体架构
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# BatchCompute 整体架构

## BatchCompute 入口

- 批量计算服务提供基于 RESTful 风格的 API。在 API 之上,用户可以通过 SDK,命令行工具,控制台等方式使用批量计算。
- 您可以使用这些工具向 BatchCompute 提交作业,查询作业运行状态,并管理作业生命周期(比如停止已提交的作业,释放已完成的作业等)。

![总体印象](http://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/pic/42382/cn_zh/1468318746090/framework.png)

## 运行环境

BatchCompute 允许用户通过自定义虚拟机镜像或者 Docker 的方式对运行环境进行高度定制,可以支持 Windows 和 Linux 操作系统。用户程序运行在隔离的虚拟化环境中,确保用户环境和用户数据的安全性。

## 持久化存储

- BatchCompute 可以使用对象存储 OSS 或者文件存储 NAS 作为输入输出数据的持久化存储。
- 用户的程序、自定义 Docker 镜像、作业的运行日志存储在 OSS 中。

+ 48
- 0
docs/alicloud_batch_compute/2.功能特性.md View File

@@ -0,0 +1,48 @@
---
id: bc-features
title: 批量计算功能特性
sidebar_label: 功能特性
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 功能特性

## 提交作业

用户使用工具(如 SDK,命令行工具等)向 BatchCompute 提交作业,BatchCompute 使用用户指定的镜像(如:ubuntu)启动虚拟机(VM), 在虚拟机中运行用户程序, 运行完成后释放虚拟机(VM)。

BatchCompute 中使用 OSS 作为持久化存储。您可以在程序运行完成时将结果数据保存到 OSS 中。在批量计算中,也可以通过文件接口的方式访问 OSS 上的数据,请参阅 OSS 挂载功能。

BatchCompute 程序默认运行在 VM 中,也支持 Docker 容器。 也就是说,您可以自定义 ECS 镜像或者使用 Docker,在镜像中安装自己需要的任何软件,用来运行您的任何程序。

作业描述
用户需要提交一个作业(Job)描述 JSON 文件到批量计算服务,该 JSON 文件中详细描述了需要执行哪些程序(支持多个程序),运行哪些程序需要启动多少台机器,机器的规格(内存和 CPU 等),运行日志打印到哪里,完成后结果输出到哪里等。

一个作业(Job)包含多个任务(Task), 按照您指定 DAG 描述的顺序执行。

![dag-tasks](http://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/pic/42382/cn_zh/1468318787552/dag-tasks.png)

每个任务定义了使用哪个镜像,使用什么实例规格,运行哪个程序,需要多少台机器运行,还有结果存储在哪里等。

![task](http://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/pic/42382/cn_zh/1469498741945/3.png)

## 管理我的作业

您可以使用工具(控制台,命令行工具等),查看我提交的作业,可以停止,重启,或删除作业。 查看各个任务的情况,各个实例(VM 实例)的情况和日志。下图是控制台的作业管理界面:

![console-jobs](http://docs-aliyun.cn-hangzhou.oss.aliyun-inc.com/assets/pic/27996/intl_zh/1524795921082/%E5%B1%8F%E5%B9%95%E5%BF%AB%E7%85%A7%202018-04-27%20%E4%B8%8A%E5%8D%8810.23.39.png)

## 使用集群

由于每次运行程序前需要启动虚拟机,会占用一定的时间(一般几分钟左右),遇到忙时有可能申请不到资源(虚拟机被其他客户使用了),您提交作业后可能需要等待一段时间才能运行。

如果您想要提高运行效率,可以先创建好集群,指定需要的虚拟机数量(比如:5 台)和镜像 ID,BatchCompute 会为您分配好机器并启动,这些机器会一直处于运行状态,一旦您提交作业上来,就可以直接运行,效率较高。

## 自定义镜像

您提交作业或者创建集群时,可以使用批量计算官方提供的镜像,也可以使用自定义镜像。自定义镜像的好处是,可以自己安装需要的软件。

+ 37
- 0
docs/alicloud_batch_compute/3.名词解释.md View File

@@ -0,0 +1,37 @@
---
id: bc-words
title: 批量计算名词解释
sidebar_label: 名词解释
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 名词解释

## 作业

用户的每个特定的计算需求在 BatchCompute 中被描述为一个作业(Job)。在 BatchCompute 系统中,用户可以通过命令行工具、管理控制台或 SDK 提交、管理和查询作业。

## 任务

一个作业由一组任务(Task)及其依赖关系组成。批量计算支持能以有向无环图 DAG(directed acyclic graph)形式描述的作业。任务间的依赖关系只能在作业提交时指定,提交完成后不能修改。

## 实例

每个任务可以有一个或多个执行实例(Instance)。同一任务的各个实例并行处理各自的输入数据。实例是 BatchCompute 调度与执行的最小单元,这些实例会动态的运行在系统分配的虚拟服务器节点上。

## 集群

一系列的 VM 实例组在 BatchCompute 中被定义为一个集群(Cluster)。一个集群可以由多个实例组(Group)组成,一个组中的实例共享同样的实例类型定义(如指定的 CPU 核数和内存大小组合),多个组之间共享镜像(Image)。有关集群的使用方式请参考 [使用集群](https://help.aliyun.com/document_detail/28018.html)。

## 镜像

镜像(Image)是集群资源创建或者作业运行环境的模板。它是一个标准的或者自定义的 ECS 镜像,需要安装 BatchCompute Agent,然后授权给 BatchCompute 服务使用。关于镜像的具体使用方法请参考 [使用镜像](https://help.aliyun.com/document_detail/28017.html)以及 [自定义镜像](https://help.aliyun.com/document_detail/44571.html)。

## Docker 镜像

使用官方提供的 ubuntu 镜像(内置 Docker 容器支持),可以支持自定义 Docker 镜像。自定义 Docker 镜像像普通镜像一样,可以自己安装运行作业的各种程序。具体方法请看这里: [使用 Docker](https://help.aliyun.com/document_detail/28022.html)。

+ 43
- 0
docs/alicloud_batch_compute/4.准备工作.md View File

@@ -0,0 +1,43 @@
---
id: bc-prepare
title: 批量计算准备工作
sidebar_label: 准备工作
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 准备工作

## 1. 创建阿里云账号

如果您还没有阿里云账号,请登陆[阿里云官网](http://www.aliyun.com/),点击右上角“免费注册”创建阿里云账号。

## 2. 开通 BatchCompute

使用注册成功的阿里云账号登陆,点菜单中“产品”,在“弹性计算”中找到批量计算(BatchCompute)进入 [产品主页](https://www.aliyun.com/product/batchcompute),开通 BatchCompute 服务。

## 3. 获取 AccessKeyId 和 AccessKeySecret

进入 [AK 控制台](https://ak-console.aliyun.com/) 获取 AccessKeySecret:

找到启用状态的 AccessKeyId 点击显示,即可获取对应的 AccessKeySecret。

如果没有可用的 AccessKeyId 可点击右上角的”创建 Access Key”按钮,创建成功后,系统会生成一对 AccessKeyId 和 AccessKeySecret。

## 4. 理解基本概念

为更好的继续下面的操作,首先简单理解 BatchCompute 中的几个 [核心概念](https://help.aliyun.com/document_detail/27995.html)。

## 5. 关于 OSS

批量计算服务默认使用 OSS 作为持久化存储, 所以很有必要先花 10 分钟时间了解 [OSS](https://help.aliyun.com/product/8314910_oss.html)。

如果您已经对 OSS 有所了解,请忽略。

## 6. 选择合适的工具

[使用 Choppy 命令行工具](../../choppy简介.md):适合初级用户。命令行工具实现了自动化的程序打包上传和作业提交,用户无需了解阿里云批量计算,亦无需了解 WDL 相关细节。只需依赖于 Choppy App 的帮助文档,准备 Samples 文件即可提交作业,开始相关数据分析。Choppy App 均被托管到[Choppy App Store](http://choppy.3steps.cn),快去找找有没有符合你要求的 App,开始数据分析之旅吧。

+ 37
- 0
docs/alicloud_batch_compute/5.支持地域.md View File

@@ -0,0 +1,37 @@
---
id: bc-regions
title: 批量计算支持地域
sidebar_label: 支持地域
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 支持地域

目前,批量计算服务支持的地域已覆盖亚洲、欧洲、北美洲。全部可用的地域(Region)如下:

### 国内部分

| RegionId | 地域 |
| -------------- | ----------------- |
| cn-qingdao | 华北1(青岛) |
| cn-beijing | 华北2(北京) |
| cn-zhangjiakou | 华北3(张家口) |
| cn-huhehaote | 华北5(呼和浩特) |
| cn-hangzhou | 华东1(杭州) |
| cn-shanghai | 华东2(上海) |
| cn-shenzhen | 华南1(深圳) |

### 国外部分

| RegionId | 地域 |
| -------------- | ---------------- |
| ap-southeast-1 | 新加坡 |
| eu-central-1 | 德国(法兰克福) |
| us-west-1 | 美国(硅谷) |
| us-east-1 | 美国(弗吉尼亚) |


+ 43
- 0
docs/alicloud_oss/0.什么是对象存储.md View File

@@ -0,0 +1,43 @@
---
id: oss-intro
title: 什么是对象存储
sidebar_label: 什么是对象存储
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 什么是对象存储

阿里云对象存储服务(Object Storage Service,简称 OSS),是阿里云提供的海量、安全、低成本、高可靠的云存储服务。它具有与平台无关的 RESTful API 接口,能够提供 99.999999999%(11 个 9)的数据可靠性和 99.99%的服务可用性。您可以在任何应用、任何时间、任何地点存储和访问任意类型的数据。

您可以使用阿里云提供的 API、SDK 接口或者 OSS 迁移工具轻松地将海量数据移入或移出阿里云 OSS。数据存储到阿里云 OSS 以后,您可以选择标准类型(Standard)的阿里云 OSS 服务作为移动应用、大型网站、图片分享或热点音视频的主要存储方式,也可以选择成本更低、存储期限更长的低频访问类型(Infrequent Access)和归档类型(Archive)的阿里云 OSS 服务作为不经常访问数据的备份和归档。

## 相关概念

- 存储类型(Storage Class)

OSS 提供标准、低频访问、归档三种存储类型,全面覆盖从热到冷的各种数据存储场景。其中标准存储类型提供高可靠、高可用、高性能的对象存储服务,能够支持频繁的数据访问;低频访问存储类型适合长期保存不经常访问的数据(平均每月访问频率 1 到 2 次),存储单价低于标准类型;归档存储类型适合需要长期保存(建议半年以上)的归档数据,在三种存储类型中单价最低。详情请参见**存储类型介绍**。

- 存储空间(Bucket)

存储空间是您用于存储对象(Object)的容器,所有的对象都必须隶属于某个存储空间。您可以设置和修改存储空间属性用来控制地域、访问权限、生命周期等,这些属性设置直接作用于该存储空间内所有对象,因此您可以通过灵活创建不同的存储空间来完成不同的管理功能。

- 对象/文件(Object)

对象是 OSS 存储数据的基本单元,也被称为 OSS 的文件。对象由元信息(Object Meta),用户数据(Data)和文件名(Key)组成。对象由存储空间内部唯一的 Key 来标识。对象元信息是一个键值对,表示了对象的一些属性,比如最后修改时间、大小等信息,同时您也可以在元信息中存储一些自定义的信息。

- 地域(Region)

地域表示 OSS 的数据中心所在物理位置。您可以根据费用、请求来源等综合选择数据存储的地域。详情请参见**访问域名和数据中心**。

- 访问域名(Endpoint)

Endpoint 表示 OSS 对外服务的访问域名。OSS 以 HTTP RESTful API 的形式对外提供服务,当访问不同地域的时候,需要不同的域名。通过内网和外网访问同一个地域所需要的域名也是不同的。具体的内容请参见**访问域名和数据中心**。

- 访问密钥(AccessKey)

AccessKey,简称 AK,指的是访问身份验证中用到的 AccessKeyId 和 AccessKeySecret。OSS 通过使用 AccessKeyId 和 AccessKeySecret 对称加密的方法来验证某个请求的发送者身份。AccessKeyId 用于标识用户,AccessKeySecret 是用户用于加密签名字符串和 OSS 用来验证签名字符串的密钥,其中 AccessKeySecret 必须保密。

+ 67
- 0
docs/alicloud_oss/1.存储类型介绍.md View File

@@ -0,0 +1,67 @@
---
id: oss-storage-type
title: 存储类型介绍
sidebar_label: 存储类型介绍
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 存储类型介绍

OSS提供标准、低频访问、归档三种存储类型,全面覆盖从热到冷的各种数据存储场景。

## 标准存储类型(Standard)

OSS标准存储类型提供高可靠、高可用、高性能的对象存储服务,能够支持频繁的数据访问。OSS高吞吐和低延时的服务响应能力能够有效支持各种热点类型数据的访问。标准存储类型是各种社交、分享类的图片、音视频应用、大型网站、大数据分析的合适选择。

关键特性:

- 99.999999999%的数据可靠性
- 按照99.99%服务可用性设计
- 低延时、高吞吐的访问性能
- 支持HTTPS加密传输
- 支持图片处理

## 低频访问存储类型(Infrequent Access)

OSS低频访问存储类型适合长期保存不经常访问的数据(平均每月访问频率1到2次)。存储单价低于标准类型,适合各类移动应用、智能设备、企业数据的长期备份,支持实时数据访问。低频访问存储类型的Object有最短存储时间,存储时间短于30天的Object提前被删除会产生一定费用。低频访问存储Object有最小计量空间,Object大小低于64KB,会按照64KB计算存储空间,数据获取会产生费用。

关键特性:

- 99.999999999%的数据可靠性
- 按照99.99%服务可用性设计
- 支持实时访问
- 支持HTTPS加密传输
- 支持图片处理
- 有最短存储时间和最小计量空间

## 归档存储类型(Archive)

OSS归档存储类型在三种存储类型中单价最低,适合需要长期保存(建议半年以上)的归档数据,在存储周期内极少被访问,数据进入到可读取状态需要1分钟的解冻时间。适合需要长期保存的档案数据、医疗影像、科学资料、影视素材。归档存储类型的Object有最短存储时间,存储时间短于60天的Object提前删除会产生一定费用。归档类型存储Object有最小计量空间,Object大小低于64KB,会按照64KB计算存储空间,数据获取会产生费用。

关键特性:

- 99.999999999%的数据可靠性
- 按照99.99%服务可用性设计
- 已经存储的数据从冷冻状态恢复到可读取状态需要1分钟的等待时间
- 支持HTTPS加密传输
- 支持图片处理,但需要先解冻
- 有最短存储时间和最小计量空间

## 存储类型对比

| 对比指标 | 标准存储类型 | 低频访问存储类型 | 归档存储类型 |
| ---------------- | -------------------- | ---------------------------- | --------------------------------------------------------- |
| 数据可靠性 | 99.999999999% | 99.999999999% | 99.999999999% |
| 服务设计的可用性 | 99.99% | 99.99% | 99.99% (数据解冻之后) |
| 对象最小计量大小 | 按照对象实际大小计算 | 64KB | 64KB |
| 最少存储时间 | 无最短存储实际要求 | 30天 | 60天 |
| 数据取回费用 | 不收取数据取回费用 | 按实际获取的数据收取,单位GB | 按实际解冻的数据量收取,单位GB |
| 数据访问特点 | 实时访问 ms延迟 | 实时访问 ms延迟 | 数据需要先解冻,解冻完成后才能读取,解冻时间需要1分钟时间 |
| 图片处理 | 支持 | 支持 | 支持,但需要先解冻 |

> 说明: “数据取回费用”中的数据是从底层分布式存储系统读取的数据量,在公网传输的数据量会计入到流出流量的计费项中。

+ 107
- 0
docs/alicloud_oss/2.访问域名和数据中心.md View File

@@ -0,0 +1,107 @@
---
id: oss-regions
title: 访问域名和数据中心
sidebar_label: 访问域名和数据中心
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 访问域名和数据中心

## OSS开通Region和Endpoint对照表

经典网络情况下各地域Endpoint的内外网设置如下:

| Region中文名称 | Region英文表示 | 外网Endpoint | 外网支持HTTPS | ECS访问的内网Endpoint | 内网支持HTTPS |
| ----------------------- | ------------------ | ------------------------------- | ------------- | ---------------------------------------- | ------------- |
| 华东 1 | oss-cn-hangzhou | oss-cn-hangzhou.aliyuncs.com | 是 | oss-cn-hangzhou-internal.aliyuncs.com | 是 |
| 华东 2 | oss-cn-shanghai | oss-cn-shanghai.aliyuncs.com | 是 | oss-cn-shanghai-internal.aliyuncs.com | 是 |
| 华北 1 | oss-cn-qingdao | oss-cn-qingdao.aliyuncs.com | 是 | oss-cn-qingdao-internal.aliyuncs.com | 是 |
| 华北 2 | oss-cn-beijing | oss-cn-beijing.aliyuncs.com | 是 | oss-cn-beijing-internal.aliyuncs.com | 是 |
| 华北 3 | oss-cn-zhangjiakou | oss-cn-zhangjiakou.aliyuncs.com | 是 | oss-cn-zhangjiakou-internal.aliyuncs.com | 是 |
| 华北 5 | oss-cn-huhehaote | oss-cn-huhehaote.aliyuncs.com | 是 | oss-cn-huhehaote-internal.aliyuncs.com | 是 |
| 华南 1 | oss-cn-shenzhen | oss-cn-shenzhen.aliyuncs.com | 是 | oss-cn-shenzhen-internal.aliyuncs.com | 是 |
| 香港 | oss-cn-hongkong | oss-cn-hongkong.aliyuncs.com | 是 | oss-cn-hongkong-internal.aliyuncs.com | 是 |
| 美国西部 1 (硅谷) | oss-us-west-1 | oss-us-west-1.aliyuncs.com | 是 | oss-us-west-1-internal.aliyuncs.com | 是 |
| 美国东部 1 (弗吉尼亚) | oss-us-east-1 | oss-us-east-1.aliyuncs.com | 是 | oss-us-east-1-internal.aliyuncs.com | 是 |
| 亚太东南 1 (新加坡) | oss-ap-southeast-1 | oss-ap-southeast-1.aliyuncs.com | 是 | oss-ap-southeast-1-internal.aliyuncs.com | 是 |
| 亚太东南 2 (悉尼) | oss-ap-southeast-2 | oss-ap-southeast-2.aliyuncs.com | 是 | oss-ap-southeast-2-internal.aliyuncs.com | 是 |
| 亚太东南 3 (吉隆坡) | oss-ap-southeast-3 | oss-ap-southeast-3.aliyuncs.com | 是 | oss-ap-southeast-3-internal.aliyuncs.com | 是 |
| 亚太东南 5 (雅加达) | oss-ap-southeast-5 | oss-ap-southeast-5.aliyuncs.com | 是 | oss-ap-southeast-5-internal.aliyuncs.com | 是 |
| 亚太东北 1 (日本) | oss-ap-northeast-1 | oss-ap-northeast-1.aliyuncs.com | 是 | oss-ap-northeast-1-internal.aliyuncs.com | 是 |
| 亚太南部 1 (孟买) | oss-ap-south-1 | oss-ap-south-1.aliyuncs.com | 是 | oss-ap-south-1-internal.aliyuncs.com | 是 |
| 欧洲中部 1 (法兰克福) | oss-eu-central-1 | oss-eu-central-1.aliyuncs.com | 是 | oss-eu-central-1-internal.aliyuncs.com | 是 |
| 英国(伦敦) | oss-eu-west-1 | oss-eu-west-1.aliyuncs.com | 是 | oss-eu-west-1-internal.aliyuncs.com | 是 |
| 中东东部 1 (迪拜) | oss-me-east-1 | oss-me-east-1.aliyuncs.com | 是 | oss-me-east-1-internal.aliyuncs.com | 是 |

> 说明
>
> - 在分享链接或者做自定义域名绑定(CNAME)的时候建议使用三级域名,即`Bucket` + `Endpoint`的形式。以华东2地域内名为oss-sample的Bucket为例,三级域名为oss-sample.oss-cn-shanghai.aliyuncs.com。
>
> - 使用SDK时,请将 `http://` 或 `https://` + `Endpoint` 作为初始化的参数。以华东2的Endpoint为例,建议将初始化参数设置为`http://oss-cn-shanghai.aliyuncs.com` 或者 `https://oss-cn-shanghai.aliyuncs.com`,不建议将三级域名(即`http://bucket.oss-cn-shanghai.aliyuncs.com`)作为初始化参数。
> - 原地址oss.aliyuncs.com 默认指向华东1 地域外网地址。原内网地址oss-internal.aliyuncs.com 默认指向华东 1 地域内网地址。

## VPC网络下Region和Endpoint对照表

在VPC网络下的ECS访问OSS可以使用如下的Endpoint:

| Region中文名称 | Region英文表示 | VPC网络Endpoint | 支持HTTPS |
| ----------------------- | ------------------ | ---------------------------------------- | --------- |
| 华东 1 | oss-cn-hangzhou | oss-cn-hangzhou-internal.aliyuncs.com | 是 |
| 华东 2 | oss-cn-shanghai | oss-cn-shanghai-internal.aliyuncs.com | 是 |
| 华北 1 | oss-cn-qingdao | oss-cn-qingdao-internal.aliyuncs.com | 是 |
| 华北 2 | oss-cn-beijing | oss-cn-beijing-internal.aliyuncs.com | 是 |
| 华北 3 | oss-cn-zhangjiakou | oss-cn-zhangjiakou-internal.aliyuncs.com | 是 |
| 华北 5 | oss-cn-huhehaote | oss-cn-huhehaote-internal.aliyuncs.com | 是 |
| 华南 1 | oss-cn-shenzhen | oss-cn-shenzhen-internal.aliyuncs.com | 是 |
| 香港 | oss-cn-hongkong | oss-cn-hongkong-internal.aliyuncs.com | 是 |
| 美国西部 1 (硅谷) | oss-us-west-1 | oss-us-west-1-internal.aliyuncs.com | 是 |
| 美国东部 1 (弗吉尼亚) | oss-us-east-1 | oss-us-east-1-internal.aliyuncs.com | 是 |
| 亚太东南 1 (新加坡) | oss-ap-southeast-1 | oss-ap-southeast-1-internal.aliyuncs.com | 是 |
| 亚太东南 2 (悉尼) | oss-ap-southeast-2 | oss-ap-southeast-2-internal.aliyuncs.com | 是 |
| 亚太东南 3 (吉隆坡) | oss-ap-southeast-3 | oss-ap-southeast-3-internal.aliyuncs.com | 是 |
| 亚太东南 5 (雅加达) | oss-ap-southeast-5 | oss-ap-southeast-5-internal.aliyuncs.com | 是 |
| 亚太东北 1 (日本) | oss-ap-northeast-1 | oss-ap-northeast-1-internal.aliyuncs.com | 是 |
| 亚太南部 1 (孟买) | oss-ap-south-1 | oss-ap-south-1-internal.aliyuncs.com | 是 |
| 欧洲中部 1 (法兰克福) | oss-eu-central-1 | oss-eu-central-1-internal.aliyuncs.com | 是 |
| 英国(伦敦) | oss-eu-west-1 | oss-eu-west-1-internal.aliyuncs.com | 是 |
| 中东东部 1 (迪拜) | oss-me-east-1 | oss-me-east-1-internal.aliyuncs.com | 是 |

## 如何使用访问域名

- 关于OSS域名的构成规则以及如何使用内网和外网访问OSS,请参见**OSS访问域名使用规则**。
- 如果您是ECS用户,需要使用OSS内网地址,请参见 **ECS用户如何正确使用OSS内网地址**。

## ECS用户如何正确使用OSS内网地址

如果您所购买的ECS实例与OSS Bucket所在地域(region)相同,那么推荐您通过内网的方式访问OSS,不收取流量费用。访问是否走内网是根据您设置的域名(endpoint)来确定的。使用了内网域名访问数据会走内网通道,如果没有使用内网域名,那么会走公网通道。

> **说明:**
>
> - 同地域的ECS可以通过内网访问OSS。
> - 跨账户的ECS和OSS可以内网互连。
> - 不同地域的ECS与OSS无法通过内网访问。

## 内网地址组成

- VPC/经典网络ECS:BucketName.region-internal.aliyuncs.com

**举例说明:**

- 华东2 VPC/经典网络ECS:aliyun-abc.oss-cn-shanghai-internal.aliyuncs.com

Region和endpoint请参考:**访问域名和数据中心**中的Region和Endpoint对照表。

## OSS访问域名的使用规则

详细的OSS外网、内网访问规则和拼写规则请参考:**OSS访问域名使用规则**。

## 通过控制台快速获得Bucket对应内网地址

在**阿里云OSS管理控制台**选择具体Bucket打开Bucket**概览**页面,在**访问域名**区域显示Bucket地址,如下图所示。

![bucket域名截图](http://kancloud.nordata.cn/2019-01-16-020417.png)

+ 102
- 0
docs/alicloud_oss/3.OSS访问域名使用规则.md View File

@@ -0,0 +1,102 @@
---
id: oss-rules
title: OSS访问域名使用规则
sidebar_label: OSS访问域名使用规则
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# OSS 访问域名使用规则

## OSS 域名构成规则

针对 OSS 的网络请求,除了 GetService 这个 API 以外,其他所有请求的域名都是带有指定 Bucket 信息的三级域名组成的。

访问域名规则:BucketName.Endpoint。其中 Endpoint 表示 OSS 对外服务的访问域名。OSS 以 HTTP RESTful API 的形式对外提供服务,当访问不同的 Region 的时候,需要不同的访问域名。Endpoint 分内网和外网访问域名。例如华东 1 Region 的外网 Endpoint 是 oss-cn-hangzhou.aliyuncs.com,内网 Endpoint 是 oss-cn-hangzhou-internal.aliyuncs.com,Region 和 Endpoint 对照表请参考[访问域名和数据中心](./2.访问域名和数据中心.md)。

## 通过外网访问 OSS 服务

外网指的是互联网。通过外网访问产生的流入流量(写)是免费的,流出流量(读)是收费的。

外网访问 OSS 有如下两种方式:

- 访问方式 1:在访问的时候以 URL 的形式来表示 OSS 的资源。OSS 的 URL 构成如下:

```
<Schema>://<Bucket>.<外网Endpoint>/<Object>
```

- Schema:HTTP 或者为 HTTPS
- Bucket:OSS 存储空间
- Endpoint:Bucket 所在数据中心的访问域名,您需要填写外网 Endpoint
- Object:上传到 OSS 上的文件

示例:如您的 Region 为华东 1(oss-cn-hangzhou),Bucket 名称为 abc,Object 名称为 myfile/aaa.txt,那么您的外网访问地址为:

```
abc.oss-cn-hangzhou.aliyuncs.com/myfile/aaa.txt
```

您还可以直接将 Object 的 URL 放入 HTML 中使用,如下所示:

```
<img src="https://abc.oss-cn-hangzhou.aliyuncs.com/mypng/aaa.png" />
```

- 访问方式 2: 通过 OSS SDK 配置外网访问域名。

OSS SDK 会对您的每一个操作拼接访问域名。但您在对不同地域的 Bucket 进行操作的时候需要设置不同的 Endpoint。

以 Java SDK 为例,对华东 1 的 Bucket 进行操作时,需要在对类实例化时设置 Endpoint:

```
String accessKeyId = "<key>";
String accessKeySecret = "<secret>";
String endpoint = "oss-cn-hangzhou.aliyuncs.com";
OSSClient client = new OSSClient(endpoint, accessKeyId, accessKeySecret);
```

## 通过内网访问 OSS 服务

内网指的是阿里云产品之间的内网通信网络,例如您通过 ECS 云服务器访问 OSS 服务。内网产生的流入和流出流量均免费,但是请求次数仍会计费。

内网访问 OSS 有如下两种方式:

- 访问方式 1:在访问的时候以 URL 的形式来表示 OSS 的资源。OSS 的 URL 构成如下。

```
<Schema>://<Bucket>.<内网Endpoint>/<Object>
```

- Schema:HTTP 或者为 HTTPS
- Bucket:OSS 存储空间
- Endpoint:Bucket 所在数据中心的访问域名,您需要填写内网 Endpoint
- Object:上传到 OSS 上的文件

示例:如您在 Region 为华东 1,Bucket 名称为 abc ,Object 名称为 myfile/aaa.txt,那么您的内网访问地址为:

```
abc.oss-cn-hangzhou-internal.aliyuncs.com/myfile/aaa.txt
```

- 访问方式 2:通过 ECS 使用 OSS SDK 配置内网访问域名。

以 Java SDK 为例,对华东 1 地域的 Bucket 进行操作时,需要在对类实例化时设置 Endpoint:

```
String accessKeyId = "<key>";
String accessKeySecret = "<secret>";
String endpoint = "oss-cn-hangzhou-internal.aliyuncs.com";
OSSClient client = new OSSClient(endpoint, accessKeyId, accessKeySecret);
```

**注意** 同一个 Region 的 ECS 和 OSS 之间内网互通,不同 Region 的 ECS 和 OSS 之间内网不互通。

例如您购买了华北 2(oss-cn-beijing)的 ECS,其 OSS 有两个 Bucket:

- 其中一个 Bucket 为 beijingres,Region 为华北 2,那么在华北 2 的 ECS 中可以使用`beijingres.oss-cn-beijing-internal.aliyuncs.com`来访问 beijingres 的资源。
- 另外一个 Bucket 为 qingdaores,Region 为华北 1,那么在华北 2 的 ECS 用内网地址`qingdaores.oss-cn-qingdao-internal.aliyuncs.com`是无法访问 OSS 的,必须使用外网地址`qingdaores.oss-cn-qingdao.aliyuncs.com`。

+ 39
- 0
docs/alicloud_oss/4.功能概览.md View File

@@ -0,0 +1,39 @@
---
id: oss-features
title: OSS功能概览
sidebar_label: 功能概览
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 功能概览

在使用OSS产品之前,建议您先了解存储空间、对象、地域、访问域名等基本概念,以便更好地理解OSS提供的功能。

关于OSS基本概念的含义,请您参见[基本概念介绍](https://help.aliyun.com/document_detail/31827.html#concept-izx-fmt-tdb)。

OSS提供以下功能:

| 应用场景 | 功能描述 | 参考 |
| ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 上传文件 | 上传文件到OSS前,必须先在阿里云的任意一个地域创建一个存储空间。创建存储空间后,您可以上传任意文件到该存储空间。 | [创建存储空间](https://help.aliyun.com/document_detail/31842.html#concept-ntj-wx1-5db) [新建文件夹](https://help.aliyun.com/document_detail/31910.html#concept-ohr-sqg-vdb) [简单上传](https://help.aliyun.com/document_detail/31848.html#concept-bws-3bb-5db) |
| 搜索文件 | 您可以在存储空间中搜索文件或文件夹。 | [搜索文件](https://help.aliyun.com/document_detail/31911.html#concept-pfs-f4l-vdb) |
| 查看或下载文件 | 您可以通过文件 URL 查看或者下载文件。 | [获取文件访问地址](https://help.aliyun.com/document_detail/31912.html#concept-k4p-dvl-vdb) |
| 删除文件或文件夹 | 您可以删除单个或者多个文件/文件夹,还可以删除分片上传产生的碎片,节省您的存储空间。 | [删除对象](https://help.aliyun.com/document_detail/31862.html#concept-g42-bhd-5db) [删除文件夹](https://help.aliyun.com/document_detail/31915.html#concept-v5p-b4m-vdb) [管理碎片](https://help.aliyun.com/document_detail/31916.html#concept-r3h-c1y-5db) |
| 控制OSS资源的访问权限 | 您可以通过以下方式控制OSS资源的访问权限: ACL:OSS 为权限控制提供访问控制列表(ACL)。ACL是授予存储空间和对象访问权限的访问策略。 您可以在创建存储空间或上传对象时配置ACL,也可以在创建存储空间或上传对象后的任意时间内修改ACL。 Bucket Policy:您可以通过控制台的Bucket Policy功能方便直观地授权其他用户访问您的OSS资源,例如向其他账号的RAM用户授予访问权限,以及向匿名用户授予带特定IP条件限制的访问权限。 RAM Policy:您可以构建RAM Policy来控制存储空间和文件夹的访问权限。OSS提供了[RAM策略编辑器](https://help.aliyun.com/document_detail/32203.html#concept-mx2-yb4-vdb)帮助您快速生成RAM Policy。 | [设置存储空间ACL](https://help.aliyun.com/document_detail/31843.html#concept-fnt-4z1-5db) [设置文件ACL](https://help.aliyun.com/document_detail/52284.html#concept-h2y-r4l-vdb) [Bucket Policy](https://help.aliyun.com/document_detail/85111.html#concept-ahc-tx4-j2b) [RAM Policy](https://help.aliyun.com/document_detail/31867.html#concept-e4s-mhv-tdb) |
| 记录OSS资源的访问信息 | 您可以开启日志功能自动记录对OSS资源的详细访问信息。 | [设置访问日志记录](https://help.aliyun.com/document_detail/31868.html#concept-t3h-4hd-5db) |
| 防止OSS上的数据被其他人盗链 | 您可以为您的存储空间设置防盗链,包括 Referer 字段的白名单和是否允许 Referer 字段为空的请求访问。 | [设置防盗链](https://help.aliyun.com/document_detail/31869.html#concept-s5b-gjd-5db) |
| 使用自定义域名访问OSS资源 | 您可以将自定义域名绑定到OSS存储空间,然后使用自定义域名访问存储空间中的数据。您还可以启用阿里云CDN服务加速对存储空间中数据的访问。如果您的域名需要通过 HTTPS 的方式访问 OSS 服务,可以通过OSS 托管您的证书。 | [绑定自定义域名](https://help.aliyun.com/document_detail/31836.html#concept-rz2-xg5-tdb) [绑定CDN加速域名](https://help.aliyun.com/document_detail/97687.html#concept-eyf-fvh-wfb) [证书托管](https://help.aliyun.com/document_detail/97187.html#concept-b2m-5mq-5fb) |
| 跨域资源共享 | OSS提供在HTML5协议中跨域资源共享(CORS)的设置。 CORS允许在一个域名中加载的客户端Web应用程序与另一个域中的资源进行交互。 | [设置跨域访问](https://help.aliyun.com/document_detail/31870.html#concept-bwn-tjd-5db) |
| 在指定时间自动批量删除文件 | 您可以定义和管理存储空间内所有文件或特定文件的生命周期。例如,达到指定天数后,将特定文件删除或者转换到其他价格更低的存储类型。 | [管理对象生命周期](https://help.aliyun.com/document_detail/31863.html#concept-y2g-szy-5db) |
| 将一个存储空间的数据跨区域复制到另一个存储空间 | 跨区域复制是对不同区域的存储空间中的文件进行自动异步复制。 跨区域复制将新创建的文件、文件更新和文件删除等操作从源存储空间复制到不同区域的目标存储空间。 | [管理跨区域复制](https://help.aliyun.com/document_detail/31864.html#concept-zjp-31z-5db) |
| 获取源数据内容 | 您可以创建回源规则来定义通过镜像还是重定向获取源数据。回源规则通常用于数据热迁移和重定向特定请求。 | [管理回源设置](https://help.aliyun.com/document_detail/31865.html#concept-n34-q1z-5db) |
| 修改 HTTP头 | 通过设置 HTTP 头来自定义HTTP请求的策略,例如缓存策略、文件强制下载策略等。 | [设置文件HTTP头](https://help.aliyun.com/document_detail/31913.html#concept-pk1-sxl-vdb) |
| 查看资源使用情况 | 您可以查看OSS服务使用情况的实时信息,如基本的系统运行状态和性能。 | [监控服务概览](https://help.aliyun.com/document_detail/31876.html#concept-j5q-hlj-5db) |
| 处理OSS中存储的图片 | 您可以对OSS中存储的图片执行不同的操作,例如格式转换、裁剪、缩放、旋转、水印和样式封装。 | [快速使用OSS图片服务](https://help.aliyun.com/document_detail/44686.html#concept-m4f-dcn-vdb) |
| 使用工具管理OSS资源 | OSS提供图形化工具、命令行工具、文件挂载工具、FTP工具等方便您管理OSS资源。 | [OSS常用工具汇总](https://help.aliyun.com/document_detail/44075.html#concept-owg-knn-vdb) |
| 使用API和SDK管理OSS资源 | OSS 提供 RESTful API和各种语言的SDK开发包方便您快速进行二次开发。 | [API 参考](https://help.aliyun.com/document_detail/31947.html#concept-whm-jcq-tdb) [SDK 参考](https://help.aliyun.com/document_detail/52834.html) |

+ 128
- 0
docs/alicloud_oss/5.基本概念介绍.md View File

@@ -0,0 +1,128 @@
---
id: oss-basic-concepts
title: 基本概念介绍
sidebar_label: 基本概念介绍
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 基本概念介绍

本部分将向您介绍本产品中涉及的几个基本概念,以便于您更好地理解对象存储 OSS 产品。

## 存储空间(Bucket)

存储空间是您用于存储对象(Object)的容器,所有的对象都必须隶属于某个存储空间。您可以设置和修改存储空间属性用来控制地域、访问权限、生命周期等,这些属性设置直接作用于该存储空间内所有对象,因此您可以通过灵活创建不同的存储空间来完成不同的管理功能。

- 同一个存储空间的内部是扁平的,没有文件系统的目录等概念,所有的对象都直接隶属于其对应的存储空间。
- 每个用户可以拥有多个存储空间。
- 存储空间的名称在 OSS 范围内必须是全局唯一的,一旦创建之后无法修改名称。
- 存储空间内部的对象数目没有限制。

存储空间的命名规范如下:

- 只能包括小写字母、数字和短横线(-)。
- 必须以小写字母或者数字开头和结尾。
- 长度必须在3–63字节之间。

## 对象/文件(Object)

对象是 OSS 存储数据的基本单元,也被称为 OSS 的文件。对象由元信息(Object Meta),用户数据(Data)和文件名(Key)组成。对象由存储空间内部唯一的 Key 来标识。对象元信息是一个键值对,表示了对象的一些属性,比如最后修改时间、大小等信息,同时用户也可以在元信息中存储一些自定义的信息。

对象的生命周期是从上传成功到被删除为止。在整个生命周期内,对象信息不可变更。重复上传同名的对象会覆盖之前的对象,因此,OSS 不支持修改文件的部分内容等操作。

OSS 提供了追加上传功能,用户可以使用该功能不断地在Object尾部追加写入数据。

对象的命名规范如下:

- 使用UTF-8编码。

- 长度必须在1–1023字节之间。

- 不能以正斜线(/)或者反斜线(\)开头。

> **说明** 对象名称需要区分大小写。如无特殊说明,本文档中的对象、文件称谓等同于 Object。

## Region(地域)

Region 表示 OSS 的数据中心所在的地域,物理位置。用户可以根据费用、请求来源等综合选择数据存储的 Region。一般来说,距离用户更近的 Region 访问速度更快。详情请查看[OSS 已经开通的 Region](https://help.aliyun.com/document_detail/31837.html#concept-zt4-cvy-5db)。

Region是在创建 Bucket 的时候指定的,一旦指定之后就不允许更改。该 Bucket 下所有的 Object 都存储在对应的数据中心,目前不支持 Object 级别的 Region 设置。

## Endpoint(访问域名)

Endpoint 表示 OSS 对外服务的访问域名。OSS 以 HTTP RESTful API 的形式对外提供服务,当访问不同的 Region 的时候,需要不同的域名。通过内网和外网访问同一个 Region 所需要的 Endpoint 也是不同的。例如杭州 Region 的外网 Endpoint 是 oss-cn-hangzhou.aliyuncs.com,内网 Endpoint 是 oss-cn-hangzhou-internal.aliyuncs.com。具体的内容请参见[各个 Region 对应的 Endpoint](https://help.aliyun.com/document_detail/31837.html#concept-zt4-cvy-5db)。

## AccessKey(访问密钥)

AccessKey,简称 AK,指的是访问身份验证中用到的 AccessKeyId 和AccessKeySecret。OSS 通过使用 AccessKeyId 和 AccessKeySecret 对称加密的方法来验证某个请求的发送者身份。AccessKeyId 用于标识用户,AccessKeySecret 是用户用于加密签名字符串和 OSS 用来验证签名字符串的密钥,其中 AccessKeySecret 必须保密。对于 OSS 来说,AccessKey 的来源有:

- Bucket 的拥有者申请的 AccessKey。
- 被 Bucket 的拥有者通过 RAM 授权给第三方请求者的 AccessKey。
- 被 Bucket 的拥有者通过 STS 授权给第三方请求者的 AccessKey。

更多 AccessKey 介绍请参见[访问控制](https://help.aliyun.com/document_detail/31867.html#concept-e4s-mhv-tdb)。

## 强一致性

Object 操作在 OSS 上具有原子性,操作要么成功要么失败,不会存在有中间状态的Object。OSS 保证用户一旦上传完成之后读到的 Object 是完整的,OSS 不会返回给用户一个部分上传成功的 Object。

Object 操作在 OSS 上同样具有强一致性,用户一旦收到了一个上传(PUT)成功的响应,该上传的 Object 就已经立即可读,并且数据的三份副本已经写成功。不存在一种上传的中间状态,即 read-after-write 却无法读取到数据。对于删除操作也是一样的,用户删除指定的 Object 成功之后,该 Object 立即变为不存在。

## OSS与文件系统的对比

| 对比项 | OSS | 文件系统 |
| -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| 数据模型 | OSS 是一个分布式的对象存储服务,提供的是一个 Key-Value 对形式的对象存储服务。 | 文件系统是一种典型的树状索引结构。 |
| 数据获取 | 根据 Object 的名称(Key)唯一的获取该Object的内容。 虽然用户可以使用类似 test1/test.jpg 的名字,但是这并不表示用户的 Object 是保存在test1 目录下面的。对于 OSS 来说,test1/test.jpg 仅仅只是一个字符串,和a.jpg 这种并没有本质的区别。因此不同名称的 Object 之间的访问消耗的资源是类似的。 | 一个名为 test1/test.jpg 的文件,访问过程需要先访问到 test1 这个目录,然后再在该目录下查找名为 test.jpg 的文件。 |
| 优势 | 支持海量的用户并发访问。 | 支持文件的修改,比如修改指定偏移位置的内容、截断文件尾部等。也支持文件夹的操作,比如重命名目录、删除目录、移动目录等非常容易。 |
| 劣势 | OSS 保存的 Object 不支持修改(追加写 Object 需要调用特定的接口,生成的 Object 也和正常上传的 Object 类型上有差别)。用户哪怕是仅仅需要修改一个字节也需要重新上传整个 Object。 OSS可以通过一些操作来模拟类似文件夹的功能,但是代价非常昂贵。比如重命名目录,希望将 test1 目录重命名成 test2,那么 OSS 的实际操作是将所有以 test1/ 开头的 Object 都重新复制成以 test2/ 开头的 Object,这是一个非常消耗资源的操作。因此在使用 OSS 的时候要尽量避免类似的操作。 | 受限于单个设备的性能。访问越深的目录消耗的资源也越大,操作拥有很多文件的目录也会非常慢。 |

因此,将 OSS 映射为文件系统是非常低效的,也是不建议的做法。如果一定要挂载成文件系统的话,建议尽量只做写新文件、删除文件、读取文件这几种操作。使用 OSS 应该充分发挥其优点,即海量数据处理能力,优先用来存储海量的非结构化数据,比如图片、视频、文档等。

以下是OSS与文件系统的概念对比:

| 对象存储 OSS | 文件系统 |
| --------------------------- | -------------- |
| Object | 文件 |
| Bucket | 主目录 |
| Region | 无 |
| Endpoint | 无 |
| AccessKey | 无 |
| 无 | 多级目录 |
| GetService | 获取主目录列表 |
| GetBucket | 获取文件列表 |
| PutObject | 写文件 |
| AppendObject | 追加写文件 |
| GetObject | 读文件 |
| DeleteObject | 删除文件 |
| 无 | 修改文件内容 |
| CopyObject (目的和源相同) | 修改文件属性 |
| CopyObject | 复制文件 |
| 无 | 重命名文件 |

## OSS 术语表

| 英文 | 中文 |
| ------------------------- | ----------------------------------------------- |
| Bucket | 存储空间 |
| Object | 对象或者文件 |
| Endpoint | OSS 访问域名 |
| Region | 地域或者数据中心 |
| AccessKey | AccessKeyId 和 AccessKeySecret 的统称,访问密钥 |
| Put Object | 简单上传 |
| Post Object | 表单上传 |
| Multipart Upload | 分片上传 |
| Append Object | 追加上传 |
| Get Object | 简单下载 |
| Callback | 回调 |
| Object Meta | 文件元信息。用来描述文件信息,例如长度,类型等 |
| Data | 文件数据 |
| Key | 文件名 |
| ACL (Access Control List) | 存储空间或者文件的权限 |

> **说明** 如果没有特殊说明,本文中出现和术语表中相同的英文和中文,表达的是相同的意思。有时候为了表述方便会混合使用。

+ 71
- 0
docs/alicloud_oss/6.存储类型转换.md View File

@@ -0,0 +1,71 @@
---
id: oss-storage-type-transform
title: OSS存储类型转换
sidebar_label: 存储类型转换
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 存储类型转换

## 通过生命周期设置存储类型自动转换

OSS 支持三种[存储类型](https://help.aliyun.com/document_detail/51374.html#concept-fcn-3xt-tdb):标准类型、低频访问类型、归档类型。

OSS 生命周期管理(Lifecycle)提供 Object Transition 机制,支持以下存储类型的自动转换:

- 标准类型转换为低频访问类型
- 标准类型转换为归档类型
- 低频访问类型转换为归档类型

![img](http://kancloud.nordata.cn/2019-01-16-015558.png)

举例

对一个 Bucket 里特定前缀的 Object 配置 Lifecycle 策略如下:

- 存储 30 天后,自动转换到低频访问类型。
- 180 天后,自动转换到归档类型。
- 超过 360 天后,文件会被自动删除。

您可以通过控制台完成以上 Lifecycle 策略的配置。具体操作请参见[设置生命周期](https://help.aliyun.com/document_detail/31904.html#concept-bmx-p2f-vdb)。

![img](http://kancloud.nordata.cn/2019-01-16-015556.png)

说明

如果一个 Bucket 同时配置了 Object 保留指定天数后转换到低频访问、Object 保留指定天数后转换到归档冷备和 Object 保留指定天数后删除,各规则设置的天数必须满足以下规则:

转换到低频的天数 < 转换到归档的天数 < 指定天数后删除

注意事项

Object 类型转换后,会按照转换后的存储类型的存储单价计算存储费用。低频访问类型和归档存储类型需要特别注意:

- 最小计量空间

对于小于 64KB 的 Object,会按照 64KB 计算空间大小。

- 最短存储周期

存储的数据需要至少保存 30 天,删除短于 30 天的文件,会收取提前删除费用。

- 归档类型的 Restore 时间

归档类型 Object 恢复到可读取状态(Restore)需要 1 分钟的解冻时间。所以如果业务场景上需要实时读取,建议只转换成低频访问存储类型,而不应转换成归档存储类型,避免转换成归档类型后,数据无法实时读取。

- 数据获取费用

低频访问类型和归档类型会收取数据获取费用,与流出流量是独立计费项,如果每个 Object 平均访问频率高于每月 1 次,不建议转换成低频访问或者归档类型。

## 其他方式的存储类型转换

对于需要将归档类型重新转换为标准类型或低频类型,低频类型转换为标准类型,可以通过读取 Object 重新写入到相对应存储类型 Bucket 来实现存储类型转换,Object 的缺省存储类型由 Bucket 决定。

例如,用户需要对在标准类型 Bucket 中已经存储成低频访问类型的 Object 重新转换成标准类型 Object,可以通过读取此 Object 后重新写入,根据 Bucket 的类型,新写入的 Object 是标准存储类型。

对于已经转储成归档类型的 Object,需要先执行 Restore 操作,解冻成可读取状态后,才能被读取。详情请参见[使用归档存储类型](https://help.aliyun.com/document_detail/54509.html#concept-wx5-szt-tdb)。

+ 109
- 0
docs/alicloud_oss/7.创建和使用归档存储类型.md View File

@@ -0,0 +1,109 @@
---
id: oss-archive-type
title: 创建和使用归档存储类型
sidebar_label: 创建和使用归档存储类型
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-17

# 创建和使用归档存储类型

OSS 提供三种存储类型,本文介绍归档存储类型(Archive)的存储空间的创建与使用。

## 创建归档存储类型的存储空间

您可以通过控制台、API/SDK 和命令行工具创建归档存储类型的存储空间。

- 通过控制台创建

通过控制台创建归档存储类型的存储空间,存储类型选择归档,如下图所示。

![img](http://kancloud.nordata.cn/2019-01-16-15703.png)

- 通过 API/SDK 创建

以 Java SDK 为例:

```
OSSClient ossClient = new OSSClient(endpoint, accessKeyId, accessKeySecret);
CreateBucketRequest createBucketRequest=new CreateBucketRequest(bucketName);
// 设置bucket权限为公共读,默认是私有读写 createBucketRequest.setCannedACL(CannedAccessControlList.PublicRead);
// 设置bucket存储类型为归档类型,默认是标准类型
createBucketRequest.setStorageClass(StorageClass.Archive);
ossClient.createBucket(createBucketRequest);
```

`createBucketRequest.setStorageClass(StorageClass.Archive);`即设置创建的存储空间的存储类型为归档存储类型。

- 通过 OSS 命令行工具创建

以 OSSUtil 为例:

```
./ossutil mb oss://[bucket name] --storage-class=Archive
```

`[bucket name]`为需要创建的存储空间名称。指定`--storage-class`的参数为`Archive`,用来创建归档存储类型的存储空间。

## 使用归档存储类型

- 上传数据

归档存储类型存储空间支持 PutObject 和 MultipartUpload 两种上传方式,不支持 AppendObject。基于 PutObject 和 MultipartUpload 开发的上传应用可以直接使用归档存储类型。

- 下载数据

归档存储类型的数据读取方式与标准存储类型和低频访问类型的数据读取方式有所区别。归档类型数据在读取前需要先执行 restore 操作解冻到可读取状态,解冻过程需要 1 分钟时间。

归档文件的状态变换过程如下:

1. 归档类型的文件初始时处于冷冻状态。
2. 提交解冻(restore)操作后,服务端执行解冻,文件处于解冻中状态。
3. 完成解冻后,可以读取文件。
4. 解冻状态默认持续 1 天,最多延长 7 天,之后文件又回到冷冻状态。

解冻方式有如下几种:

- 使用控制台解冻

![img](http://kancloud.nordata.cn/2019-01-16-015702.png)

对需要读取的文件,执行解冻操作,解冻过程预计花费 1 分钟。期间可以查询到 object 处于解冻中状态。

![img](http://kancloud.nordata.cn/2019-01-16-015704.png)

- 使用 API/SDK 解冻

以 Java SDK 举例,调用 restoreObject 方法进行 object 解冻:

```
ObjectMetadata objectMetadata = ossClient.getObjectMetadata(bucketName, key);
// check whether the object is archive class
StorageClass storageClass = objectMetadata.getObjectStorageClass();
if (storageClass == StorageClass.Archive) {
// restore object
ossClient.restoreObject(bucketName, key);
// wait for restore completed
do {
Thread.sleep(1000);
objectMetadata = ossClient.getObjectMetadata(bucketName, key);
} while (!objectMetadata.isRestoreCompleted());
}
// get restored object
OSSObject ossObject = ossClient.getObject(bucketName, key);
ossObject.getObjectContent().close();
```

- 使用 OSS 命令行工具解冻

以 OSSUtil 为例:

```
./ossutil restore oss://[Bucket name]/[Object name]
```

`[Bucket name]`和`[Object name]`为需要做解冻操作的 bucket 和 object 名称。

+ 6
- 0
docs/book.json View File

@@ -0,0 +1,6 @@
{
"plugins": [
"highlight",
"copy-code"
]
}

+ 7
- 0
docs/choppy-docs.code-workspace View File

@@ -0,0 +1,7 @@
{
"folders": [
{
"path": "."
}
]
}

+ 121
- 0
docs/choppy_app/0.概要.md View File

@@ -0,0 +1,121 @@
---
id: choppy-app-intro
title: Choppy App概要
sidebar_label: 概要
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-16

# Choppy App 定义概要

Choppy App 是一种定义 Pipeline 分析流程的技术规范,它约定了 WDL 撰写和文件命名等规范,并结合模板语言将用户的 Pipeline 封装成 App,同时提供基于模板的校验、逻辑控制等能力来帮助用户开发出功能比单个 WDL 更为强大的应用。

简单的理解,Choppy App 是基于 WDL ( Workflow Definition Language ) 的功能更强大的 Workflow 定义语言。同时因为遵循同一套开发规范,使得不同用户开发出来的 App 可以直接复用,而无需做任何修改与调整。

`Choppy App = WDL + 模板语言 + 开发规范`,正因为 Choppy App 是基于 WDL 进阶开发而成的,因此开发 Choppy App 前,用户一般需要将自己的 Pipeline 改写成 WDL 的形式,而后再基于自己对 Pipeline 控制能力的要求,通过引入模板表达式和遵循 Choppy App 开发规范将 WDL 以及相关的 Inputs 文件封装成 App。

## WDL 参考文档

详见`WDL定义`

## 模板语言

模板仅仅是文本文件,在 Choppy App 中用户实际上定义的是 WDL + Inputs 模板文件,而非真正可用于任务运行的 WDL 文件。在 App 实际运行时,Choppy 会读取 WDL + Inputs 模板文件,并识别其中用模板语言语法定义的表达式,而后计算渲染成实际可运行的 WDL 文件,投递到 Cromwell 中。

模板包含`变量`或`表达式`,这两者在模板求值的时候会被替换为真实值。模板中还有标签,控制模板的逻辑。

下面是一个最小的模板,它向大家展示了基于模板语言撰写的 Inputs 模板文件和 WDL 模板文件。

```jinja2
{
"{{ project_name }}.read1": "{{ read1 }}",
"{{ project_name }}.read2": "{{ read2 }}",
"{{ project_name }}.adapter": "oss://pgx-storage-results/yangjingcheng/reference/illumina_adapter/TruSeq3-PE.fa",
"{{ project_name }}.idx": "oss://pgx-storage-results/yangjingcheng/reference/index/hisat2/",
"{{ project_name }}.gtf": "oss://pgx-storage-results/yangjingcheng/reference/annotation/gencode.v22.annotation.gtf",
{% if sample_name is not None %}
"{{ project_name }}.baseout": "FUSCCTNBC007",
{% endif %}
"{{ project_name }}.idx_prefix": "GRCh38_d1_vd1",
"{{ project_name }}.fastqc.docker": "localhost:5000/fastqc:latest oss://pgx-docker-images/dockers",
"{{ project_name }}.fastqc.cluster": "OnDemand ecs.sn1.xlarge img-ubuntu-vpc",
"{{ project_name }}.trimmomatic.docker": "localhost:5000/trimmomatic:v0.38 oss://pgx-docker-images/dockers",
"{{ project_name }}.trimmomatic.cluster": "OnDemand ecs.sn1.xlarge img-ubuntu-vpc",
"{{ project_name }}.hisat2.docker": "localhost:5000/hisat2:v2.0.5-1-deb-cv1 oss://pgx-docker-images/dockers",
"{{ project_name }}.hisat2.cluster": "OnDemand ecs.sn2ne.4xlarge img-ubuntu-vpc",
"{{ project_name }}.samtools.docker": "localhost:5000/samtools:latest oss://pgx-docker-images/dockers",
"{{ project_name }}.samtools.cluster": "OnDemand ecs.sn2.xlarge img-ubuntu-vpc",
"{{ project_name }}.stringtie.docker": "localhost:5000/stringtie:v1.3.4 oss://pgx-docker-images/dockers",
"{{ project_name }}.stringtie.cluster": "OnDemand ecs.sn1.xlarge img-ubuntu-vpc"
}
```

```jinja2
import "./tasks/fastqc.wdl" as fastqc
import "./tasks/trimmomatic.wdl" as trimmomatic
import "./tasks/hisat2.wdl" as hisat2
import "./tasks/samtools.wdl" as samtools
import "./tasks/stringtie.wdl" as stringtie

workflow {{ project_name }} {

File read1
File read2
File adapter
File idx
String idx_prefix
String baseout
File gtf

scatter ( read in [read1, read2]) {
call fastqc.qc as fastqc {input: read=read}
}

call trimmomatic.trimmomatic as trimmomatic {
input: baseout=baseout, read1=read1, read2=read2, adapter=adapter
}

call hisat2.hisat2 as hisat2 {
input: idx=idx, idx_prefix=idx_prefix, read_1P=trimmomatic.read_1p, read_2P=trimmomatic.read_2p
}

call samtools.samtools as samtools {
input: sam = hisat2.sam
}

call stringtie.stringtie as stringtie {
input: gtf = gtf, bam = samtools.out_bam
}

output {
Array[File] fastqc_html = fastqc.html
Array[File] fastqc_zip = fastqc.zip
File fastq_1p = trimmomatic.read_1p
File fastq_2p = trimmomatic.read_2p
File bam = samtools.out_bam
File bam_index = samtools.out_bam_index
}
}
```

上述两个文件展示了模板中最常见的表达式和变量的定义形式,比如{{ project_name }}变量和{% if sample_name is not None %}表达式等。这里有两种分隔符: `{% ... %}` 和 `{{ ... }}` 。前者用于执行诸如 for 循环、if 条件表达式或赋值的语句,后者把表达式的结果打印到模板上。

## App 开发流程

1. 将原有 Bash 脚本或者新的 Pipeline 的命令汇总,而后按照单条命令的粒度拆分;(粒度的控制取决于多方面的因素,若你无法区分粒度划分带来的影响,建议按照单条命令进行拆分)

2. 一条命令对应一个 task,参照`WDL定义`章节的说明,将单条命令拆分成四个组成部分:输入变量、命令参数、运行时环境、输出文件。以此将所有命令用 WDL 语言表述为 task 描述文件。

3. 按照 Pipeline 定义的流程,将 task 组装成一个完整的 workflow 描述文件

4. Follow Choppy App 规范的要求,将所有 task 描述文件统一放到 tasks 目录下,而 workflow 描述文件命名为 workflow.wdl,此外 inputs 文件为 workflow 变量的输入文件。

> 特别注意:变量的命名以及 task 依赖的引入

5. 将所有 wdl 描述文件和 inputs 文件中需要 App 用户从 samples 文件传入的部分替换为模板变量和或模板表达式。此后 choppy 可以直接读入 wdl 描述文件和 inputs 文件,从中抽取出 App 开发者定义的变量,并以此生成 samples 文件。App 用户只需要依此准备 samples 文件即可将 App 中的模板变量替换成自己预期的值,并渲染生成真实的 WDL 文件。

> 需要注意的是,在 choppy 中为了使得用户分析数据得到的结果隔离开来,强制要求 workflow.wdl 文件中 workflow 的名字为{{ project_name }}

+ 18
- 0
docs/choppy_app/1.变量.md View File

@@ -0,0 +1,18 @@
---
id: choppy-app-vars
title: Choppy App模板变量
sidebar_label: 模板变量
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-16

# 变量

定义在模板中的所有变量的具体值均取决于你同时定义的 `samples 文件`,Choppy 会负责读入 `samples 文件`并解析为 Key:Value 的形式传入模板中。比如你在模板中定义了 `{{ read1 }}` 变量,当你通过 choppy 调用某个 app 时,choppy 会读入你指定的 samples 文件,从中解析出 read1 的值,而后将模板中的 read1 变量替换为真实的值。至此就可以通过 samples 文件来生成真实的 WDL 和 Inputs 文件。

> 1. 在此需要注意的是:花括号是用来标识变量本身的,并非变量的一部分。只有这样 choppy 才能知晓你在模板中定义了哪些变量。
> 2. 当你定义的变量无法从 samples 文件中取到值时,choppy 默认会将其替换为空字符串。此时可能导致任务运行失败,因此你定义模板时需要对这种非预期行为进行预判并做相应的处理。比如,提供默认值或者对输入值进行过滤等。

+ 141
- 0
docs/choppy_app/2.表达式.md View File

@@ -0,0 +1,141 @@
---
id: choppy-app-expression
title: Choppy App模板表达式
sidebar_label: 模板表达式
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-16

# 表达式

模板中允许使用基本表达式。这像常规的 Python 一样工作,即使你不用 Python 工作,你也会感受到其带来的便利。

### 字面量

表达式最简单的形式就是字面量。字面量表示诸如字符串和数值的 Python 对象。下面 的字面量是可用的:

- “Hello World”:

双引号或单引号中间的一切都是字符串。无论何时你需要在模板中使用一个字 符串(比如函数调用、过滤器或只是包含或继承一个模板的参数),它们都是 有用的。

- 42 / 42.23:

直接写下数值就可以创建整数和浮点数。如果有小数点,则为浮点数,否则为 整数。记住在 Python 里, `42` 和 `42.0` 是不一样的。

- true / false:

true 永远是 true ,而 false 始终是 false 。

提示

特殊常量 true 、 false 和 none 实际上是小写的。因为这在过去会导致混淆,过去 True 扩展为一个被认为是 false 的未定义的变量。所有的这三个常量也可以被写成首字母大写( True 、 False 和 None )。尽管如此, 为了一致性(所有的模板中的标识符是小写的),你应该使用小写的版本。

### 算术

模板中允许使用计算值。这在模板中很少用到,但是为了完整性允许其存在。支持下面的运算符:

- +

把两个对象加到一起。通常对象是素质,但是如果两者是字符串或列表,你可以用这 种方式来衔接它们。无论如何这不是首选的连接字符串的方式!连接字符串见 `~` 运算符。 `{{ 1 + 1 }}` 等于 `2` 。

- -

用第一个数减去第二个数。 `{{ 3 - 2 }}` 等于 `1` 。

- /

对两个数做除法。返回值会是一个浮点数。 `{{ 1 / 2 }}` 等于 `{{ 0.5 }}` 。

- //

对两个数做除法,返回整数商。 `{{ 20 // 7 }}` 等于 `2` 。

- %

计算整数除法的余数。 `{{ 11 % 7 }}` 等于 `4` 。

- \*

用右边的数乘左边的操作数。 `{{ 2 * 2 }}` 会返回 `4` 。也可以用于重 复一个字符串多次。 `{{ ‘=’ * 80 }}` 会打印 80 个等号的横条。

- \*\*

取左操作数的右操作数次幂。 `{{ 2**3 }}` 会返回 `8` 。

### 比较

- ==

比较两个对象是否相等。

- !=

比较两个对象是否不等。

- >

如果左边大于右边,返回 true 。

- > =

如果左边大于等于右边,返回 true 。

- <

如果左边小于右边,返回 true 。

- <=

如果左边小于等于右边,返回 true 。

### 逻辑

对于 if 语句,在 if 表达式中,它可以用于联合多个表达式:

- and

如果左操作数和右操作数同为真,返回 true 。

- or

如果左操作数和右操作数有一个为真,返回 true 。

- not

对一个表达式取反。

- (expr)

表达式组。

### 其它运算符

下面的运算符非常有用,但不适用于其它的两个分类:

- is

类似于 Python 中的 `is`,可用于判断变量,比如 `if var is None`

- |

应用一个 过滤器,详见`过滤器`章节。

- ~

把所有的操作数转换为字符串,并且连接它们。 `{{ "Hello " ~ name ~ "!" }}` 会返回(假设 name 值为 `''John'` ) `Hello John!` 。

### If 表达式

同样,也可以使用内联的 if 表达式。这在某些情况很有用。例如你可以用来在一个变量定义的情况下才使用它,否则使用预设的默认值:

```
{% my_variable if my_variable is defined else 'default_variable' %}
```

一般的语法是 `<do something> if <something is true> else <do something else>` 。

else 部分是可选的。如果没有显式地提供 else 块,会求值一个未定义对象:

+ 69
- 0
docs/choppy_app/3.过滤器.md View File

@@ -0,0 +1,69 @@
---
id: choppy-app-filter
title: Choppy App过滤器
sidebar_label: 模板过滤器
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-16

# 过滤器

变量可以通过 **过滤器** 修改。过滤器与变量用管道符号( `|` )分割,并且也 可以用圆括号传递可选参数。多个过滤器可以链式调用,前一个过滤器的输出会被作为 后一个过滤器的输入。

例如 `{{ name|striptags|title }}` 会移除 name 中的所有 HTML 标签并且改写 为标题样式的大小写格式。过滤器接受带圆括号的参数,如同函数调用。这个例子会 把一个列表用逗号连接起来: `{{ list|join(', ') }}` 。

下面的 内置过滤器清单 节介绍了所有的内置过滤器。

## 内置过滤器清单

1. `default(value, default_value=u'', boolean=False)`

如果`my_variable`的值未定义,表达式将返回 default 函数中设置的值。否则将返回`my_variable`的值

```
{{ my_variable | default('my_variable is not defined') }}
```

2. `capitalize(str)`

将`str`字符串首字母变换为大写

3. `lower(str)`

将`str`字符串所有字符变换为小写

4. `upper(str)`

将`str`字符串所有字符变换为大写

5. `wordcount(str)`

计算字符串`str`中单词数目

6. `trim(str)`

去除字符串`str`前后空白字符,如空格、Tab 等

7. `replace(str, old, new, count=None)`

模式匹配并替换,将`str`字符串中满足模式匹配的子字符串替换为新字符串。`old`是用于模式匹配的字符串,`new`是用于替换满足模式匹配的子字符串的字符串。`count`指定替换次数。具体示例如下:

```
{{ "Hello World"|replace("Hello", "Goodbye") }}
-> Goodbye World

{{ "aaaaargh"|replace("a", "d'oh, ", 2) }}
-> d'oh, d'oh, aaargh
```

8. `int(value, default=0)`

将`value`的值转换成整数,如果转换不成功则默认返回 0 或其它整数

9. `float(value, default=0.0)`

将`value`的值转换成浮点数,如果转换不成功则默认返回 0.0 或其它浮点数

+ 41
- 0
docs/choppy_app/4.空白控制.md View File

@@ -0,0 +1,41 @@
---
id: choppy-app-whitespace
title: Choppy App空白控制
sidebar_label: 模板空白控制
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-16

# 空白控制

默认配置中,模板引擎不会对空白做进一步修改,所以每个空白(空格、制表符、换行符 等等)都会原封不动返回。如果应用配置了 Jinja 的 trim_blocks ,模板标签后的第一个换行符会被自动移除。

此外,你也可以手动设置标记,以便模板引擎移除模板中的空白。如当你在块(比如一个 for 标签、一段注释或变 量表达式)的开始或结束放置一个减号( `-` ),可以移除块前或块后的空白:

```
{% for item in seq -%}
{{ item }}
{%- endfor %}
```

这会产出中间不带空白的所有元素。如果 seq 是 `1` 到 `9` 的数字的列表, 输出会是 `123456789` 。

## 提示

标签和减号之间不能有空白。

**有效的**:

```
{%- if foo -%}...{% endif %}
```

**无效的**:

```
{% - if foo - %}...{% endif %}
```

+ 39
- 0
docs/choppy_app/5.控制结构.md View File

@@ -0,0 +1,39 @@
---
id: choppy-app-condition
title: Choppy App控制结构
sidebar_label: 模板控制结构
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-16

# 控制结构清单

控制结构指的是所有的那些可以控制程序流的东西 —— 条件,比如 if/elif/else 之类的东西。控制结构在默认语法中以 `{% .. %}` 块的形式出现。

### If

模板中的 if 语句可比 Python 中的 if 语句。在最简单的形式中,你可以测试 一个变量是否未定义,为空或 false:

```jinja2
## 注意在json和wdl中使用模板语言时必须使得模板渲染之后的结果遵守相应的语法规范,如inputs文件渲染之后应该符合json的语法规范

{% if sample_name is not None %}
"{{ project_name }}.baseout": "FUSCCTNBC007",
{% endif %}
```

像在 Python 中一样,用 elif 和 else 来构建多个分支。你也可以用更复杂的 [_表达式_](http://docs.jinkan.org/docs/jinja2/templates.html#expressions):

```
{% if kenny.sick %}
Kenny is sick.
{% elif kenny.dead %}
You killed Kenny! You bastard!!!
{% else %}
Kenny looks okay --- so far
{% endif %}
```

+ 23
- 0
docs/choppy_app/6.注释.md View File

@@ -0,0 +1,23 @@
---
id: choppy-app-annotation
title: Choppy App注释
sidebar_label: 模板注释
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-16

# 注释

要把模板中一行的部分注释掉,默认使用 `{# ... #}` 注释语法。这在调试或 添加给你自己或其它模板设计者的信息时是有用的:

```
{# note: disabled template because we no longer use this
{% for user in users %}
...
{% endfor %}
#}
```

+ 34
- 0
docs/choppy简介.md View File

@@ -0,0 +1,34 @@
---
id: choppy-intro
title: Choppy for Reproducible Omics Pipeline
sidebar_label: Choppy 简介
---

> Author: Jingcheng Yang
>
> Email: yjcyxky@163.com
>
> Date: 2019-01-18

# Choppy for Reproducible Omics Pipeline

## 功能特点

![Choppy 的特点](http://kancloud.nordata.cn/2019-01-15-150638.png)

## Slides

![Choppy](http://kancloud.nordata.cn/2019-01-15-150640.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150641.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150650.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150651.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150652.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150655.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150656.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150658.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150700.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150704.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150707.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150708.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150709.png)
![Choppy](http://kancloud.nordata.cn/2019-01-15-150710.png)

BIN
docs/images/choppy.png View File

Before After
Width: 943  |  Height: 728  |  Size: 191KB

BIN
docs/images/choppy_ppt_1.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 197KB

BIN
docs/images/choppy_ppt_10.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 832KB

BIN
docs/images/choppy_ppt_11.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 306KB

BIN
docs/images/choppy_ppt_12.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 289KB

BIN
docs/images/choppy_ppt_13.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 537KB

BIN
docs/images/choppy_ppt_14.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 313KB

BIN
docs/images/choppy_ppt_2.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 852KB

BIN
docs/images/choppy_ppt_3.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 324KB

BIN
docs/images/choppy_ppt_4.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 395KB

BIN
docs/images/choppy_ppt_5.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 611KB

BIN
docs/images/choppy_ppt_6.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 451KB

BIN
docs/images/choppy_ppt_7.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 780KB

BIN
docs/images/choppy_ppt_8.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 745KB

BIN
docs/images/choppy_ppt_9.png View File

Before After
Width: 2000  |  Height: 1125  |  Size: 1.2MB

+ 321
- 0
docs/quick_introduction.md View File

@@ -0,0 +1,321 @@
---
id: quick-intro
title: 快速指南:Choppy for Reproducible Omics Pipeline
sidebar_label: 快速指南
---

> Author: Yechao Huang
>
> Email: 17210700095@fudan.edu.cn
>
> Date: 2019-01-18

# 快速指南:Choppy for Reproducible Omics Pipeline

## Pipeline 分析三步走

基于`Choppy平台`进行 Pipeline 分析十分简单高效,只需要三步即可轻松搞定(**点击进入[演示视频](http://kancloud.nordata.cn/2019-01-20-choppy.mp4)**):

1. 登陆**[Choppy App Store](http://choppy.3steps.cn)**,挑选符合自己需求的 App,并安装
2. 准备 App 所需的 Samples 文件
3. 提交任务

## **使用 APP 提交任务**

> 基于 choppy 封装的 app 可以使得用户可以通过自定义或者下载的 `app` 简单快速的进行可重复并且可溯源的任务提交

- 选择所要使用的 **app** 并生成相应的 **samples.csv** 文件(以 dna-germline-0.1.0 为例)

```bash
choppy samples dna-germline-0.1.0 --output dna-germline.csv
```

通过上述命令会生成一个对应于使用的 app 的一个 .csv 格式文件,按照表头的内容将所涉及到的变量(如:fastq 文件在 OSS 上的路径、对应的 sample 的名字、sample_id 等)填入到文件中(注意以 “,” 进行分隔),在填写的过程中可以直接在 linux 系统下进行操作也可以下载到本地 PC 上使用 excel 进行操作。

> sample_id : 对于每一个提交的样本名会根据 sample_id 来创建一个目录,里面包含了当前样本所运行时使用的 wdl 文件以及 input 文件,以便于对样本任务的溯源工夫

- 根据生成的 samples.csv 文件批量提交任务

```bash
choppy batch dna-germline-0.1.0 samples.csv --project-name project
```

当出现如下所示的信息时,表明当前任务提交成功:

```bash
Sample ID: 1, Workflow ID: a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f
Successed: 1, /home/huangyechao/project/submitted.csv
```

其中,第一行为所提交的样本的名字以及每一个样本对应的 workflow ID ,可用于查询该任务的运行状态;当有多个样本时,会有多行出现。
第二行为统计 app 端成功的样本数,并且会生成包含有当次任务成功提交时的所有信息
第三行为为统计 app 端失败的样本数(若没有失败则不会产生)

- 根据生成的 Workflow ID 可以进行任务状态的查询,使用命令如下

```bash
choppy query -s a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f
```

此时会显示出该样本任务的状态信息,当显示为 submitted 时,表示任务正在向云端及进行投递过程中; 显示为 Running 时,表示任务已经成功在云端运行;当显示为 Failed 时,表示任务运行失败。
使用 **-m** 参数可以查看更多关于任务的日志信息:

```bash
choppy query -s -m a6a24b7d-bea3-48fe-93f6-7b7aa8ce9b5f
```

- 当任务提交成功之后,可登陆到阿里云控制台中,在批量计算的作业列表中查询任务的运行情况;通常当任务提交到阿里云计算平台时,会需要几分钟的服务器配置时间之后任务才会开始进行计算。

## **构建属于自己 WDL**

在构建 **WDL** 之前,需要先对 **WDL** 的基本结果有一定的了解,其基本结构包含以下部分:`workflow`,`task`,`call`, `command`以及`output`(详见[WDL Base Structure](https://software.broadinstitute.org/wdl/documentation/structure))

以下是对构建 **WDL** 脚本的一个简单教程(以 [Sentieon](http://goldenhelix.com/products/sentieon/index.html) 的 DNA-seq 为例):

## 单个 task 的构建

- **command**: 通常我们在构建**pipeline** 时,是将每一步分析写入到一个脚本中,并调用脚本的方式串行使用,如下所示:

```bash
$SENTIEON_INSTALL_DIR/bin/bwa mem -M -R "@RG\tID:$group\tSM:$sample\tPL:$pl" -t $nt $fasta $fastq_1 $fastq_2 | $SENTIEON_INSTALL_DIR/bin/sentieon util sort -o ${sam}.sorted.bam -t $nt --sam2bam -i -
```

以上为 **DNA-seq** 中比对的命令,在 **WDL** 中这部分将会书写在 `command` 部分,如下所示:

```
command <<<
set -o pipefail
set -e
export SENTIEON_LICENSE=此处替换为你的license
nt=$(nproc)
${SENTIEON_INSTALL_DIR}/bin/bwa mem -M -R "@RG\tID:${group}\tSM:${sample}\tPL:${pl}" -t $nt ${ref_dir}/${fasta} ${fastq_1} ${fastq_2} | ${SENTIEON_INSTALL_DIR}/bin/sentieon util sort -o ${sample}.sorted.bam -t $nt --sam2bam -i -
>>>
```

可以看到在 **WDL** 中,就是将日常所使用的命令填入在 `command` 中,并用`{ }`或者`<<< >>>`进行引用(后者主要是在于有多个命令运行时使用)。

> 注意: `${变量}`的形式是 **WDL** 所识别的变量,当命令中的变量是`$变量`的形式时,**WDL**是无法识别的,如例子中的 `$nt` 在之前已经对其进行了定义;

- **output**: `command` 部分完成之后,需要对于该命令的输出进行定义,比对的结果产生的文件为`${sample}.sorted.bam` 以及 `${sample}.sorted.bam.bai` ,因此需要在 `output` 中对结果的输出进行定义:

```bash
output {
File sorted_bam = "${sample}.sorted.bam"
File sorted_bam_index = "${sample}.sorted.bam.bai"
}
```

左边为当前 `task` 输出结果的命名,右边为所输出结果文件名,用 `" "` 进行引用;

当有多个结果文件输出时,只有在 `output` 中进行了定义的结果文件才会输出,没有定义的将不会输出到结果目录中;

- **runtime**: 对于每一个 `task` 的运行环境需要进行定义,包括所使用的软件的 `docker`信息,所使用的服务器配置信息,以及服务器的系统盘以及数据盘大小:

```bash
runtime {
dockerTag:docker
cluster: cluster_config
systemDisk: "cloud_ssd 40"
dataDisk: "cloud_ssd " + disk_size + " /cromwell_root/"
}
```

`dockerTag` 为所使用的 `docker` 信息,此处以变量表示

`cluster` 为运行命令是所选用的服务器实例信息([参照阿里云服务器 ECS](https://help.aliyun.com/document_detail/25378.html?spm=a2c4g.11186623.6.545.8e452f98mSzIST))

`systemDisk` 为使用的系统盘的大小,默认为 cloud_ssd 40G

`dataDisk` 为使用的数据盘的大小信息,默认类型为 `cloud_ssd` ,挂载点为 `/cromwell_root/`

> 注意:在系统盘和数据盘的写法上,需注意不同的变量之间存在空格

- 在将 `command` 主体部分改写完成之后,需要在 `task` 中声明 `command` 中所使用的变量形式:

```bash
task mapping {
File fastq_1
File fastq_2
File ref_dir
String fasta
String SENTIEON_INSTALL_DIR
String group
String sample
String pl
String docker
String cluster_config
String disk_size

command <<<
....
>>>
runtime {
...
}

output {
...
}
}

```

对于在 `task` 中所使用到的变量,都需要在 `task` 上面先进行声明,通常有两种形式 `File` 以及 `String`

## workflow 的构建

> `workflow` 应用于在所有的 `task` 构建完成之后,对于每个步骤进行调用以及每个步骤之间的依赖关系的一个说明,包括以下两个部分 `import`,`call`

```bash
import "./tasks/mapping.wdl" as mapping
import "./tasks/Metrics.wdl" as Metrics

workflow sentieon {
call mapping.mapping as mapping {
input:
SENTIEON_INSTALL_DIR=SENTIEON_INSTALL_DIR,
group=sample,
sample=sample,
pl="ILLUMINAL",
....
}
call Metrics.Metrics as Metrics {
input:
....
}
}
```

- **import** :表明构建的 `workflow` 中所需要使用的步骤信息,这部分内容可根据使用者分析过程中需要的内容进行自定义:

```bash
import "./tasks/mapping.wdl" as mapping
import "./tasks/Metrics.wdl" as Metrics
import "./tasks/Dedup.wdl" as Dedup
import "./tasks/deduped_Metrics.wdl" as deduped_Metrics
import "./tasks/Realigner.wdl" as Realigner
import "./tasks/BQSR.wdl" as BQSR
import "./tasks/Haplotyper.wdl" as Haplotyper
```

引号内的内容为所要调用的 `task` 信息, `as` 之后的内容(如 `mapping` `Dedup` 等为所定义的步骤的别名)在命名时,应尽量使得命名简单并能包含所需的信息

- **call** : 是对所引用的 `task` 中的变量进行传递以及对不同的步骤之间的依赖关系进行说明:

```bash
call mapping.mapping as mapping {
input:
SENTIEON_INSTALL_DIR=SENTIEON_INSTALL_DIR,
group=sample,
sample=sample,
pl="ILLUMINAL",
fasta=fasta,
ref_dir=ref_dir,
fastq_1=fastq_1,
fastq_2=fastq_2,
docker=docker,
disk_size=disk_size,
cluster_config=cluster_config
}

call Metrics.Metrics as Metrics {
input:
SENTIEON_INSTALL_DIR=SENTIEON_INSTALL_DIR,
fasta=fasta,
ref_dir=ref_dir,
sorted_bam=mapping.sorted_bam,
sorted_bam_index=mapping.sorted_bam_index,
sample=sample,
docker=docker,
disk_size=disk_size,
cluster_config=cluster_config
}
```

首先需要对 `call` 进行声明,`mapping.mapping as mapping` 中,第一个 `mapping` 是与 `import` 中的别名保持一致,第二个 `mapping` 是与 `task` 中使用的命名保持一致(`task mapping {...}`),第三个 `mapping` 是作为在 `workflow` 中的命名; `input` 是将 `task` 中所使用的变量进行定义,`=`左边是变量名,右边是对变量的赋值,当所使用的变量会重复使用时,可以将其继续以变量的形式进行声明,并在`call`的外部进行声明;

在构建 `pipeline` 中,通常某步的输入文件是上一步的结果输出,在 `call` 中,可以通过对上一步结果文件的引用使得 `workflow` 能自动判别程序的依赖关系,并采取串行或者并行计算;如上所示,`Metrics` 的输入文件是上一步 `mapping` 的输出结果文件,因此在 `input` 中 `mapping.sorted_bam` 表明该步骤使用到 `mapping` 中的 `sorted_bam` 文件,因此只有当 `mapping` 这一步运行结束时,`Metrics` 才会启动运行。

- **变量声明**:在`workflow` 中,同样需要对 `call` 中没有赋值的变量进行声明:

```bash
File fastq_1
File fastq_2

String SENTIEON_INSTALL_DIR
String sample
String docker

File ref_dir
File dbmills_dir
File dbsnp_dir
String db_mills
String fasta
String dbsnp
String disk_size
String cluster_config
```

类似于 `task` 中的变量声明方式,需要 `File` 及 `String` 声明变量类型, 对于 `workflow` 中的变量,都会在 `input` 中进行赋值;

- **input**: 在 WDL 中所使用的变量,都会在 `input` 文件中进行赋值。变量的读取规则为,在 `call` 的内部使用的变量如果在 `workflow` 中的变量声明中同样进行了定义,则变量的传递顺序为 `input` --> `workflow` 变量声明 --> `call` ,当没有在 `workflow` 中声明,则变量的传递顺序为 `input` --> `call`

```bash
{
"sentieon.fasta": "GRCh38.d1.vd1.fa",
"sentieon.ref_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/",
"sentieon.dbsnp": "dbsnp_146.hg38.vcf",
"sentieon.fastq_1": "oss://pgx-storage-backend/WGS_germline/WGC107658D_combined_R1.fastq.gz",
"sentieon.SENTIEON_INSTALL_DIR": "/opt/sentieon-genomics",
"sentieon.dbmills_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/",
"sentieon.db_mills": "Mills_and_1000G_gold_standard.indels.hg38.vcf",
"sentieon.cluster_config": "OnDemand ecs.sn2ne.2xlarge img-ubuntu-vpc",
"sentieon.docker": "localhost:5000/sentieon-genomics:v2018.08.01 oss://pgx-docker-images/dockers",
"sentieon.dbsnp_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/",
"sentieon.sample": "WGC107658D",
"sentieon.disk_size": "500",
"sentieon.fastq_2": "oss://pgx-storage-backend/WGS_germline/WGC107658D_combined_R2.fastq.gz"
}
```

`input` 文件的生成可以使用 `womtool`(参见[womtool](https://github.com/broadinstitute/cromwell/releases/tag/36)使用), 同时也可使用 `womtool` 对所写的 **WDL** 进行验证。

```bash
java -jar womtool.jar validate 2.wdl ####WDL验证
java -jar womtool.jar inputs 3step.wdl ### 生成input文件生成
```

- **将 WDL 脚本封装成为 APP**:单个 **WDL** 文件撰写完成之后,可以通过简单的改写就可将 **WDL** 文件封装成为``choppy`中的 **APP** 使用,用于批量提交,改写规则如下:

- 将`workflow` 中的 `workflow_name`变为变量引用形式:

```bash
workflow {{ project_name }} {
...
}
```

在 `choppy` 中对于变量是通过 `{{ }}`的形式进行引用,此处 `project_name` 是在使用 **APP** 提交任务时定义的变量,可用于提交任务之后所生成的可追溯的文件;

- 将 `input` 中的相应的 `project_name` (即上面所示例子中的 `sentieon` )改为 `{{project_name}}` ;此外对于后面所需要改变的参数变量,可以使用 `{{ }}` 进行变量引用:

```bash
{
"{{ project_name }}.fasta": "GRCh38.d1.vd1.fa",
"{{ project_name }}.ref_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/",
"{{ project_name }}.dbsnp": "dbsnp_146.hg38.vcf",
"{{ project_name }}.fastq_1": "{{ read1 }}",
"{{ project_name }}.SENTIEON_INSTALL_DIR": "/opt/sentieon-genomics",
"{{ project_name }}.dbmills_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/",
"{{ project_name }}.db_mills": "Mills_and_1000G_gold_standard.indels.hg38.vcf",
"{{ project_name }}.cluster_config": "{{ cluster if cluster != '' else 'OnDemand ecs.sn1ne.4xlarge img-ubuntu-vpc' }}",
"{{ project_name }}.docker": "localhost:5000/sentieon-genomics:v2018.08.01 oss://pgx-docker-images/dockers",
"{{ project_name }}.dbsnp_dir": "oss://pgx-reference-data/GRCh38.d1.vd1/",
"{{ project_name }}.sample": "{{ sample_name }}",
"{{ project_name }}.disk_size": "{{ disk_size }}",
"{{ project_name }}.regions": "{{ regions }}",
"{{ project_name }}.fastq_2": "{{ read2 }}"
}
```

至此整个 APP 封装完毕,可以在 `choppy` 中使用

+ 262
- 0
docs/style/website.css View File

@@ -0,0 +1,262 @@
/*
* NOTE:
* - The use of browser-specific styles (-moz-, -webkit-) should be avoided.
* If used, they may not render correctly for people reading the email in
* a different browser than the one from which the email was sent.
* - The use of state-dependent styles (like a:hover) don't work because they
* don't match at the time the styles are made explicit. (In email, styles
* must be explicitly applied to all elements -- stylesheets get stripped.)
*/

/* To add site specific rules, you can use the `data-md-url` attribute that we
add to the wrapper element. Note that rules like this are used depending
on the URL you're *sending* from, not the URL where the recipient views it.
*/
/* .markdown-here-wrapper[data-md-url*="mail.yahoo."] ul { color: red; } */

pre,
code {
font-size: 0.85em;
font-family: Consolas, Inconsolata, Courier, monospace;
}

code {
margin: 0 0.15em;
padding: 0 0.3em;
white-space: pre-wrap;
border: 1px solid #eaeaea;
background-color: #f8f8f8;
border-radius: 3px;
display: inline; /* added to fix Yahoo block display of inline code */
}

pre {
font-size: 1em;
line-height: 1.2em;
}

pre code {
white-space: pre;
overflow: auto; /* fixes issue #70: Firefox/Thunderbird: Code blocks with horizontal scroll would have bad background colour */
border-radius: 3px;
border: 1px solid #ccc;
padding: 0.5em 0.7em;
display: block !important; /* added to counteract the Yahoo-specific `code` rule; without this, code blocks in Blogger are broken */
}

/* In edit mode, Wordpress uses a `* { font: ...;} rule+style that makes highlighted
code look non-monospace. This rule will override it. */
.markdown-here-wrapper[data-md-url*="wordpress."] code span {
font: inherit;
}

/* Wordpress adds a grey background to `pre` elements that doesn't go well with
our syntax highlighting. */
.markdown-here-wrapper[data-md-url*="wordpress."] pre {
background-color: transparent;
}

/* This spacing has been tweaked to closely match Gmail+Chrome "paragraph" (two line breaks) spacing.
Note that we only use a top margin and not a bottom margin -- this prevents the
"blank line" look at the top of the email (issue #243).
*/
p {
/* !important is needed here because Hotmail/Outlook.com uses !important to
kill the margin in <p>. We need this to win. */
margin: 0 0 1.2em 0 !important;
}