怎么根据TCGA官方的API下载数据？简单几句命令轻轻松松下载想要的TCGA大数据

淡淡的烟草味﹌ 2022-05-21 09:25 198阅读 0赞

### 下载文件 ###

GDC API使用`data`和`manifest`端点实现文件下载功能（说白了，就是想下载哪个文件直接根据该文件连接地址，请求下载就好了，那了每个文件连接地址是什么呢？请具体看下面教程）。 数据端点允许用户通过指定文件UUID来下载存储在GDC中的文件。 清单端点生成下载清单文件，该文件可与GDC数据传输工具一起使用以传输大量数据。

**注意**：下载受控访问数据需要使用身份验证令牌。 有关详细信息，请参阅 [Getting Started: Authentication][Getting Started_ Authentication]

**注意**：从GDC Legacy Archive下载数据的请求必须定向到旧版/数据。 有关详细信息，请参阅 [Getting Started: Legacy Archive][Getting Started_ Legacy Archive]

### Data端点 ###

要下载文件，用户可以将UUID传递到 **Data端点**。 如果提供单个UUID，API将返回关联文件。 如果提供了以逗号分隔的UUID列表，则API将返回包含所请求文件的存档文件。

**Data端点**支持GET和POST请求，如以下示例所示。

#### 相关文件 ####

如果指定了`related_files = true`参数，则GDC API将在下载包中包含以下相关文件（如果可用）：

*  BAM index files (BAI files)
 *  Metadata files (such as SRA XML or MAGE-TAB files)

例如，此请求将下载旧版拷贝编号分段文件及其关联的MAGE-TAB元数据文件：（你可以点开下面的连接，这个就是TCGA的一个文件，TCGA上每一个文件都有一个连接，我们可以直接根据连接下载文件。仔细看看这个连接有什么特点吗？没错，就是TCGA数据仓库网址加上文件的标签UUID，说白了就是前面`https://api.gdc.cancer.gov/legacy/data/` 不变，后面加上文件的UUID号 `7efc039a-fde3-4bc1-9433-2fc6b5e3ffa5`就行了，我别的文章有讲怎么使用脚本下载TCGA数据，有兴趣可以看一看。）

https://api.gdc.cancer.gov/legacy/data/7efc039a-fde3-4bc1-9433-2fc6b5e3ffa5?related_files=true

##### 使用GET下载单个文件 #####

此示例演示如何从GDC下载单个文件。 在这里，我们使用GET请求将文件的UUID传递给数据端点。  
**shell 脚本**

curl --remote-name --remote-header-name 'https://api.gdc.cancer.gov/data/5b2974ad-f932-499b-90a3-93577a9f0573'

**输出样例**

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100 6111k  100 6111k    0     0   414k      0  0:00:14  0:00:14 --:--:--  412k
    curl: Saved to filename '14-3-3_beta-R-V_GBL1112940.tif'

#### 使用GET下载多个文件 ####

此示例演示如何使用GET请求从GDC下载多个文件。 GDC API返回包含下载文件的.tar.gz存档。  
**shell 脚本**

curl --remote-name --remote-header-name 'https://api.gdc.cancer.gov/data/e3228020-1c54-4521-9182-1ea14c5dc0f7,18e1e38e-0f0a-4a0e-918f-08e6201ea140'

**输出样例**

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                   Dload  Upload   Total   Spent    Left  Speed
    100  287k    0  287k    0     0  30131      0 --:--:--  0:00:09 --:--:-- 42759
    curl: Saved to filename 'gdc_download_064d1aa8cc8cbab33e93979bebbf7d6af2d6a802.tar.gz'

**注意**：此方法支持一次下载有限数量的文件。 要下载大量文件，请使用[POST][]。

##### 下载未受压缩的文件组 #####

如果为数据端点下载查询指定了`?tarfile`参数，则下载字符串中请求的所有文件将捆绑在单个tar文件中，而不是作为默认行为的tar.gz文件。  
**shell 脚本**

curl --remote-name --remote-header-name 'https://api.gdc.cancer.gov/data/1da7105a-f0ff-479d-9f82-6c1d94456c91,77e73cc4-ff31-449e-8e3c-7ae5ce57838c?tarfile'

#### 使用POST下载多个文件 ####

以下两个示例演示如何使用POST请求从GDC下载多个文件，该请求包含两种格式之一的有效负载：百分比编码表单数据或JSON。 GDC API返回包含下载文件的.tar.gz存档。

如上所述，`data`和`legacy/data`端点都接受POST请求。

##### 请求表单数据PAYLOAD #####

携带百分比编码表单数据的payload的POST请求必须包含HTTP标头`Content-Type: application/x-www-form-urlencoded`。

payload 是以下格式的字符串：

ids=UUID1&ids=UUID2&ids=UUID3...

其中UUID＃对应于要下载的文件的UUID。

在此示例中，我们使用curl从GDC Legacy Archive下载一组文件。payload存储在名为Payload的纯文本文件中; curl默认包含`Content-Type: application/x-www-form-urlencoded`。

**Payload**

ids=556e5e3f-0ab9-4b6c-aa62-c42f6a6cf20c&ids=e0de63e2-02f3-4309-9b24-69f4c24e85fc&ids=f1a06178-2ec2-4b06-83f3-3aedac332cfe&ids=11a8aca0-c8e6-4ff8-8ab6-fe18a1b8ba82&ids=69a69c84-00de-45ff-b397-fd2b6713ed4f&ids=9ec48233-395d-401e-b205-951c971f8dd4&ids=93129547-378c-4b69-b858-532abfff678e&ids=8d4277e9-a472-4590-886d-24dc2538ea65&ids=6733b412-56da-4f1c-a12b-ff804cb656d7&ids=a72eec98-c5e0-4866-8953-765780acb6c1&ids=e77b2294-1bdd-4fba-928a-d81d2622312f&ids=965e01fc-318e-4c02-a801-d6fad60bfae4&ids=21ad5409-fe0b-4728-97e4-15520b9fc287&ids=1a777521-277c-4aeb-baf1-66871a7c2d2a&ids=c13a3449-9e0d-45a9-bcc0-518f55e45c8a&ids=5f2d329b-d59d-4112-b490-5114b830e34d&ids=bb966617-6c1f-4bb0-a1ed-ceb37ecade67&ids=05d11519-2b33-4742-aa87-3934632f2f2b&ids=39bfafe2-9628-434e-bd72-148051a47477&ids=481bea69-3cd5-45f3-8a52-2d4cc8fc8df7&ids=f95e407b-de69-416c-920c-6be8c9414862&ids=75940293-8fa6-47f9-ad5d-155b61933fdc&ids=e8e84ccf-f8a8-4551-9257-ef731d02116f&ids=e4991159-f088-4a2a-88b7-38d6ac47c6bc

**shell 脚本**

curl --remote-name --remote-header-name --request POST 'https://api.gdc.cancer.gov/legacy/data' --data @Payload

**输出样例**

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100 2562k    0 2561k  100   983   880k    337  0:00:02  0:00:02 --:--:-- 880k
    curl: Saved to filename 'gdc_download_20160701_011153.tar.gz'

##### 使用JSON PAYLOAD发布请求 #####

携带JSON有效负载的POST请求必须包含HTTP标头`Content-Type：application/json`。

payload是以下格式的字符串：

{
        "ids":[
            "UUID1",
            "UUID2",
                    ...
            "UUID3"
        ]
    }

其中UUID＃对应于要下载的文件的UUID。

在这个例子中，我们使用curl从GDC Legacy Archive下载一组文件; 有效负载存储在名为`Payload`的纯文本文件中。  
**Payload**

{
        "ids":[ "556e5e3f-0ab9-4b6c-aa62-c42f6a6cf20c", "e0de63e2-02f3-4309-9b24-69f4c24e85fc", "f1a06178-2ec2-4b06-83f3-3aedac332cfe", "11a8aca0-c8e6-4ff8-8ab6-fe18a1b8ba82", "69a69c84-00de-45ff-b397-fd2b6713ed4f", "9ec48233-395d-401e-b205-951c971f8dd4", "93129547-378c-4b69-b858-532abfff678e", "8d4277e9-a472-4590-886d-24dc2538ea65", "6733b412-56da-4f1c-a12b-ff804cb656d7", "a72eec98-c5e0-4866-8953-765780acb6c1", "e77b2294-1bdd-4fba-928a-d81d2622312f", "965e01fc-318e-4c02-a801-d6fad60bfae4", "21ad5409-fe0b-4728-97e4-15520b9fc287", "1a777521-277c-4aeb-baf1-66871a7c2d2a", "c13a3449-9e0d-45a9-bcc0-518f55e45c8a", "5f2d329b-d59d-4112-b490-5114b830e34d", "bb966617-6c1f-4bb0-a1ed-ceb37ecade67", "05d11519-2b33-4742-aa87-3934632f2f2b", "39bfafe2-9628-434e-bd72-148051a47477", "481bea69-3cd5-45f3-8a52-2d4cc8fc8df7", "f95e407b-de69-416c-920c-6be8c9414862", "75940293-8fa6-47f9-ad5d-155b61933fdc", "e8e84ccf-f8a8-4551-9257-ef731d02116f", "e4991159-f088-4a2a-88b7-38d6ac47c6bc" ] }

**shell 脚本**

curl --remote-name --remote-header-name --request POST --header 'Content-Type: application/json' --data @request.txt 'https://api.gdc.cancer.gov/legacy/data'

**输出样例**

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100 2562k    0 2561k  100  1145   788k    352  0:00:03  0:00:03 --:--:-- 788k
    curl: Saved to filename 'gdc_download_20160701_011007.tar.gz'

#### 下载受控访问文件 ####

要下载受控访问文件，必须使用 `X-Auth-Token` HTTP标头将有效的身份验证令牌传递给GDC API：  
**shell 脚本**

token=$(<gdc-token-text-file.txt)
    curl --remote-name --remote-header-name --header "X-Auth-Token: $token" 'https://api.gdc.cancer.gov/data/0eccf79d-1f1e-4205-910f-8e126b08276e'

**输出样例**

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100 31.4M  100 31.4M    0     0   290k      0  0:01:50  0:01:50 --:--:-- 172k
    curl: Saved to filename 'ACOLD_p_TCGA_Batch17_SNP_N_GenomeWideSNP_6_A03_466078.tangent.copynumber.data.txt'

--------------------

### Manifest端点 ###

Manifest端点生成可与GDC数据传输工具一起使用的下载清单文件。 建议使用数据传输工具传输大量数据。 GDC API还可以从与[搜索和检索][Link 1]查询匹配的结果列表生成下载清单。 为此，请将`&return_type = manifest`附加到查询的末尾。

#### 使用Manifest端点 ####

Manifest端点允许用户创建下载清单，该清单可与GDC数据传输工具一起使用以下载大量数据。 清单端点从逗号分隔的UUID列表生成清单文件。  
**shell 脚本**

curl --remote-name --remote-header-name 'https://api.gdc.cancer.gov/v0/manifest/ae9db773-78ab-48d0-972d-debe1bedd37d,3d815e6e-db97-419d-ad7f-dba4e4023b3e'

**输出样例**

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100   274  100   274    0     0   1042      0 --:--:-- --:--:-- --:--:--  1041
    curl: Saved to filename 'gdc_manifest_20160428_234614.txt'

`manifest`端点还支持与`data`端点格式相同的HTTP POST请求; 见上文了解详情。

##### 使用return\_type = manifest #####

或者，用户可以通过将`&return_type = manifest`附加到[搜索和检索][Link 1]查询来创建`manifest`。 在这个例子中，我们从实体组织正常样本生成RNA-seq数据文件的下载`manifest`，这是`TCGA-KIRC`项目的一部分：  
**shell 脚本**

curl --remote-name --remote-header-name 'https://api.gdc.cancer.gov/files?filters=%7B%22op%22%3A%22and%22%2C%22content%22%3A%5B%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22experimental_strategy%22%2C%22value%22%3A%5B%22RNA-Seq%22%5D%7D%7D%2C%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.project.project_id%22%2C%22value%22%3A%5B%22TCGA-KIRC%22%5D%7D%7D%2C%7B%22op%22%3A%22%3D%22%2C%22content%22%3A%7B%22field%22%3A%22cases.samples.sample_type%22%2C%22value%22%3A%5B%22Solid+Tissue+Normal%22%5D%7D%7D%5D%7D&size=30000&return_type=manifest'

**输出样例**

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                     Dload  Upload   Total   Spent    Left  Speed
    100 40663    0 40663    0     0  77109      0 --:--:-- --:--:-- --:--:-- 77306
    curl: Saved to filename 'gdc_manifest.2016-06-28T13:26:33.850459.tsv'

[Getting Started_ Authentication]: https://docs.gdc.cancer.gov/API/Users_Guide/Getting_Started/#authentication
[Getting Started_ Legacy Archive]: https://docs.gdc.cancer.gov/API/Users_Guide/Getting_Started/#gdc-legacy-archive
[POST]: https://docs.gdc.cancer.gov/API/Users_Guide/Downloading_Files/#downloading-multiple-files-using-post
[Link 1]: https://docs.gdc.cancer.gov/API/Users_Guide/Search_and_Retrieval/