本地应用规范

关于原生应用的概述，请参阅本地应用概述．

本文档涵盖了BaseSpace中原生应用基础架构的约定。这些约定中的大部分都属于我们所称的服务宇宙船坞．SpaceDock为该应用程序执行许多功能，下文将介绍。从本文档中，您将了解到以下内容:yobet亚洲

什么是spacedock.

SpaceDock是BaseSpace开发的一个Linux包，可以安装在任何希望从BaseSpace接收本地应用作业的机器上。SpaceDock是一个安装在原生应用开发者VM上的服务，它与安装在AWS实例中运行应用的服务是相同的。

当一个Native apps作业提交给BaseSpace时，BaseSpace将启动一个AWS EC2实例(或多个实例)，同时也安装了SpaceDock，你的应用程序将启动，你的应用程序的行为将与你的开发者虚拟机相同。

spacedock自动管理开发人员的几个重要功能，包括：

  • 从BaseSpace接收作业
  • 允许应用程序访问用户的数据进行分析
  • 下载输入数据到机器
  • 报告状态和记录返回给用户的BaseAck
  • 提供参考基因组数据
  • 将结果上传到BaseSpace

虽然Spacedock自动处理所有此此类，但是，只要遵循某些约定，开发人员可能希望进一步优化这些功能。在这些情况下，BaseSpace Rest API也可用于执行其中的许多功能。但在大多数情况下，应用程序不需要直接执行BaseSpace API调用，因为SpaceDock是为你设计的。

如何在虚拟机上获取spacedock

当新版本的SpaceDock发布时，它将以Debian软件包的形式提供下载。

更新现有的SpaceDock包

有两种方法可以更新spacedock。

如果您只更新计算机（或虚拟机）上的现有版本的Spacedock，请参阅以下信息。在未来，我们将释放有关如何在任何计算机上安装Spacedock包的更多信息（不限于虚拟机。）

要在您的机器上获得最新版本的SpaceDock，只需执行以下步骤:

  1. 更新机器上的所有软件包

    sudo apt-get更新

  2. 安装新更新的spacedock包

    请安装太空码头

这将使您的机器上的最新烫伤的spacedock。

第一次下载SpaceDock

如果你正在配置自己的原生应用开发机器，你需要做的一个步骤就是下载SpaceDock。

在你的机器上安装SpaceDock:

  1. 指向SpaceDock仓库并将其添加到apt-get中:

    Echo deb http://basespace-apt.s3.amazonaws.com spacedock main | sudo tee -a /etc/apt/ soures .list;

  2. 更新spacedock的软件包和策略：

    sudo apt-get更新;apt-cache政策宇宙船坞

  3. 宇宙船坞更新:

    sudo apt-get更新;请安装太空码头

SpaceDock做什么

本节将涵盖《SpaceDock》的所有开发者相关功能。

从BaseSpace接收作业

SpaceDock的主要功能是在BaseSpace中为您的应用程序轮询新的作业。SpaceDock用于创建与BaseSpace的连接。

为了让SpaceDock为您的特定应用程序投票BaseSpace for Jobs，请遵循以下步骤:

  1. 确保SpaceDock包安装在本地机器、虚拟机或实例上。位置取决于应用程序运行的位置。

  2. 为应用程序创建一个输入表单

  3. 在Forms Builder窗口中打开表单

  4. 在Forms Builder窗口的右侧，选择并复制命令示例命令行启动本地代理：，它应该看起来像这样sudo spacedock -a {Agent_Id} -m https://mission.basespace.illumina.com

  5. 将此命令粘贴到您的机器终端中（安装了应用程序的机器）

用户认证和权限

基于应用程序的输入表单，BaseSpace将自动请求必要的权限下载输入数据并将结果保存回BaseSpace，开发者不必担心这一点!SpaceDock会根据表单中要求的内容自动获得用户数据的许可，并在应用运行时存储该许可。每个表单控件都规定了用户所选择的给定资源需要的访问级别。

访问输入数据

SpaceDock在运行应用程序时要做的第一件事就是将用户选择的数据放置到应用程序可访问的位置数据文件夹，包含另外两个文件夹，输入和输出．

这输入应用程序启动时，文件夹将包含以下数据：

  • 在输入表单中选择的任何输入Sample数据都将下载到/数据/输入/样本/ < sample-id >文件夹
  • 在输入表单中选择的任何输入的apresult数据都被下载到/数据/输入/ appresults / < appresult-id >文件夹
  • 在输入表单上选择的用户选择后创建的AppSession将保存为JSON文件/ /输入/ AppSession.json数据．这个文件很重要，因为AppSession将用户在输入表单中选择的所有信息保存为AppSession的Properties。这是为了方便不需要进行API调用而持久化的获取：appsessions / {id}．请参考Rest API参考中的AppSessions获取有关AppSessions的更多信息。
  • 对于多节点应用程序，保留用户在输入表单上选择的所有信息的AppSession被保存为。json文件数据/输入文件夹parentappsession.json.．您需要解析这些信息，以找到用户在启动应用程序时所选择的内容。

下载输入数据的约定取决于为应用程序配置的Callbacks.js脚本的类型。有关Callbacks.js脚本的更多信息，请参阅Formbuilder文档．对于单节点配置，对多节点配置的约定略有不同，它们将在下面更详细地描述它们。

此外，如果在输入表单上启用了BSFS选项，应用程序将不会预先下载所有的输入数据，而是在应用程序请求时下载数据。

使用BSFS或预下载

数据可以通过两种不同的机制提供给你的容器:预下载文件或通过BaseSpace文件系统(BSFS)挂载点．

使用BSFS挂载您的数据呈现了许多相对于下载选项的好处，这就是为什么现在在开发人员门户中创建新应用程序时默认启用BSFS的原因。

本质上，开发者必须简单地为他们的callbacks.js脚本的返回值添加以下内容:

选择:“净水器。启用= true”)

这在以下单个节点示例中显示：

函数LaunchEd（DataProvider）{return {commandline：[“/ helloworld.sh”]，containerimageid：“tliu1 / helloworld”，选项：[bsfs.enabled = true“]};}

访问单个节点本机应用程序的输入数据

以下是单个节点本机应用程序的Callbacks.js脚本的示例：

函数LaunchEd（DataProvider）{return {commandline：[“/ helloworld.sh”]，containerimageid：“tliu1 / helloworld”，选项：[bsfs.enabled = true“]};}

注意选项数组，用于通过选项“bsfs.enabled = true”以启用BSF。可以使用BSFS在事件中删除该选项不需要。

当Callbacks.js脚本使用Single-Node模板时，所有的输入数据在上面引用的位置都是可用的。

使用多节点模板访问本地应用的输入数据

多节点的情况稍微复杂一些。当一个多节点应用程序启动时，一个父母AppSession是为每个节点的聚合而创建的孩子AppSession创建每个节点的分析。这父母AppSession将包含表单中的所有输入属性，但是孩子节点的AppSession需要从Callbacks.js脚本显式地分配Properties，否则它将没有Properties。下面是一个多节点本地应用的Callbacks.js脚本示例:

函数launchSpec(dataProvider) {var retval = {nodes: []};var samples = dataProvider.GetProperty("Input.samples");var apsults = dataProvider.GetProperty(" input . apsults ");For (var I = 0;我< samples.length;我+ +){retval.nodes。push({commandLine: ["/helloworld.sh"])， containerImageId:" t柳1/helloworld "，属性:{"Input. sh"， {"Input. sh";样品:[我]][样本,”输入。一种ppResults": [appresults[i]] }, Options: [ "bsfs.enabled=true" ] }); } return retval; }

在本例中，每个分析节点显式地分配了两个Properties输入。样品和Input.Aggresults.特性。这些是用户在输入表单中选择的样本和评估资源，并通过Callbacks.js脚本检索dataProvider.GetProperty ()方法。这些是完整的Sample和apresult资源。在为循环，我们可以看到每个节点都被赋予命令行参数,ContainerImageid.值指向Docker映像属性字段和选项阵列。这属性字段将为该特定节点添加指定属性，因此在这种情况下，它将位于每个样本创建的每个节点上。请注意，选项阵列中的“bsfs.enabled = true”选项是为多节点启动中的每个节点设置的。

对于多节点应用程序，输入表单中的信息将被保存到parentappsession.json.文件在数据/输入文件夹每个子节点．对于每个节点的显式设置的任何属性，它们将存储在标准中AppSession.json文件。例如，如果应用程序的表单具有许多元素，则这些值不必传递给每个节点，因为它们将被保存到parentappsession.json.文件。

目前可以传递给每个节点的属性数目25.．

此外，这个示例展示了如何命令行和ContainerImageid.在每个子节点中设置。

报告日志窗口中用户的状态和错误

当用户在BaseSpace中启动一个应用程序时，他们会被带到分析页面，在那里他们会得到关于启动的分析的更多信息。这个Analysis页面会定期刷新，更新AppSession Status和StatusSummary以及app的输出日志。

SpaceDock将自动向窗口报告一些日志，包括下载输入数据，下载docker图像，并将结果上传到BaseSpace。除了这些自动日志，应用程序还可以写回自定义消息到日志窗口。

手动写入日志窗口

写入stdout的任何内容都将写入日志窗口。这个窗口不是为了显示整个应用程序日志而设计的，而是为了显示最近活动的一小部分缓冲区。

报告错误

如果应用程序遇到轻微的错误但仍然可以继续分析，它可以使用上面的示例简单地写回日志窗口。

如果应用程序遇到致命错误当应用程序无法恢复时，应用程序应该以非零的退出状态码退出。此错误将在“日志”窗口中自动报告给“用户”，并且会话将被标记为“终止”。

上传自定义日志文件

在原生应用程序中，自定义日志文件也可以上传回BaseSpace。这些文件一旦上传，就可以通过蓝色显示日志链接在日志窗口上方的分析信息页面。

/ /日志/数据

可以将自定义日志文件写入数据/ logs /文件夹中。允许多种文件类型，非常灵活。作业结束后，这个文件夹中的日志将通过“完成”或“中止”状态上传到BaseSpace。

使用属性上传结果到BaseSpace

上传时，将输出文件放入:

/数据/输出/ appresults / <项目id > / [directory_with_appresult_name] / [your_files]

所有数据数据输出文件夹将被上传到BaseSpace，当应用程序返回退出码0.让SpaceDock知道分析是什么完整的．

控件中创建一个appsult输出文件夹，请确保在该文件夹中创建至少一个appsult的文件夹。

每个被创建的appsult都可以被单独标记为Properties。属性很重要，因为它们为用户提供了关于分析的更多信息，每个appsult应该这样做总是包含用于获取这些结果的输入。例如，如果Samples被用作输入，那么创建的presult应该被标记为input.samples指示使用哪个样本和结果的属性。开发者可以遵循一些惯例，让SpaceDock自动为他们的结果添加一些输入数据，下文将对此进行描述。

App只输出1个apresult文件夹

如果应用程序接受一个或多个Samples或apsults作为输入，但每次只产生一个apsult，该apsult将自动被标记为input.samples和Input.Aggresults.来自提交表单时创建的AppSession的属性。

匹配输入样例和输出apsult名称

如果的名字的名称与输入样本的名称相同，SpaceDock将自动标记该apresult与input.samples财产和id的样本。

手动标记每个申请人员

一种_metadata.json文件可以包含在每次评估者文件夹，这个文件只需要有以下关于apesult和Properties数组的信息。示例如下_metadata.json可以包含在appsult中的文件，appsult的名称必须与为其创建的文件夹的名称匹配：

{"Name": " myapapsult "， "Description": " myapapsult的分析结果"，"HrefAppSession": "v1pre3/appsessions/2056097"， "Properties": [{"Type": "string"， "Name": "RW_BaseSpace_App. Properties"]月"，"描述":"创建测试属性"，"内容":"1"}，{"类型":"字符串"，"名称":"RW_BaseSpace_App. Name";Day， "Description": "Testing property creation"， "Content": "20"}， {"Type": "string"， "Name": "RW_BaseSpace_App. Name"， "Description": "Testing property creation"， "Content": "20"}， {"Type": "string"， "Name": "RW_BaseSpace_App. Name"年份"，"描述":"创建测试属性"，"内容":"2014"}，{"类型":"sample[]"， "Name": "输入。示例"，"Items": ["v1pre3/ Samples /710710"]}]}

在上面的例子中，我们包含了以下信息，这些信息将被添加到BaseSpace中的appsult的元数据中(这对用户和未来的应用来说是非常有用的，可能是关于分析的更多信息):

  • 的名字: apesult的名称，必须与在数据输出/ appresults / <项目id > / < appresult-name >文件夹
  • 描述:在用户界面中显示的对apresult的描述
  • HrefAppSession:这将把一个引用到AppSession上指定的appsult, AppSessions是一种方式，用户可以在一个分析中跟踪所有的信息，所以它是重要的HrefAppSession字段。的元数据中找到的Href将是相同的appsession.json文件中的文件数据/输入文件夹时，应用程序启动。
  • 属性:一个属性数组，它将被添加到appsult的元数据中
    • 输入。样品:用户在应用程序的输入表单中选择的输入样本类型是样本[]或样本，它专门将此定义为BaseSpace中的Sample。这项目然后阵列包含一个数组hrefsample.将在此阵列中指定的示例标记Appresult的属性。
    • RW_BaseSpace_App。一年那RW_BaseSpace_App。月,RW_BaseSpace_App。一天:这些是简单的字符串属性，将被添加到apresult的属性中。

有关属性的更多信息，请参阅Rest API引用中的属性，属性可以是自由形式的，但是需要遵循一些约定来将属性指定为BaseSpace中的特定资源，例如类型是样本那样本[]那评估者,appresult []属性将作为BaseSpace资源读取，这些在上面的链接中有更多描述。有关apsults的更多信息，请参阅在Rest API参考中显示．

然后，可以使用App Report Builder工具为分析创建输出报告，一旦分析被标记为完成，这些报告就会自动生成。有关应用程序报表生成器工具的更多信息，请参阅App Report Builder文档．以下是输出报告的示例：

访问基因组参考数据的基因组文件夹

在原生应用虚拟机中，你会发现基因组文件夹中。在此文件夹中，在本地虚拟机上，您只会发现phix参考基因组。为减小虚拟机的大小，我们只有有限的基因组可用于本地测试。但是，我们正在努力将所有Igenomes和许多其他引用集成到我们的基因组文件夹中。

除此之外基因组在BaseSpace(而不是本地)中运行的Amazon Machine中的文件夹有一个更健壮的参考基因组集合。

这基因组文件夹可以复制到您的Docker映像通过遵循将文件添加到图像中．

如何确定哪些基因组是可用的

为了确定应用程序可用的基因组，我们创建了一个可以在帐户中运行的码头图像。当作为本机应用程序启动时，该Docker映像将输出具有基因组驱动器的完整结构的文本文件。

要查看完整的基因组驱动器，必须在Basespace云基础架构中运行应用程序。我们提供的VM具有有限的基因组驱动器，只有选择基因组可用。

docker镜像可以用下面的命令下拉:

sudo docker拉rwentzel / list-genomes

现在，您可以转到开发人员门户，并配置一个应用程序指向Rwentzel / list-genomes就像callbacks.js脚本中的docker图像。你的callbacks.js脚本看起来应该像下面的例子:

function launchSpec(dataProvider) {var project = dataProvider. getproperty ("Input.project-id");var apsultpatharg = "/data/output/ apsults /" + project。Id +”/结果”;var retval = {commandLine: ["/opt/illumina/list-genomes/app.sh"， "/genomes"， apsultpatharg]， containerImageId: "rwentzel/list-genomes"};}

在配置好callback .js脚本后，只需在form Builder中转到应用程序的表单并启动应用程序。

应用程序的输出将是一个基因组列表文件．

这个Docker图像可以进一步调整，以输出更详细的信息，请随意查看源代码Docker图像，以调整它，以满足您的特定需求。

在分析过程中用于存储文件的Scratch文件夹

在某些情况下，应用可能需要在计算时使用临时空间。这在BaseSpace中可用数据/划痕文件夹中。其他目录对可以添加多少数据有限制，这可能会导致应用程序失败，所以请在所有情况下使用scratch文件夹。