Toolkit 概述

简要介绍 Shotgun Pipeline Toolkit 中的各种概念。

本文档介绍仅当控制 Toolkit 配置时可用的功能。有关详细信息,请参见 Shotgun 集成管理员手册。在本文中,我们将详细介绍各种主要概念,其中包括:应用和插件的工作方式、Toolkit 如何启动和管理当前上下文(工作区)、如何在磁盘上创建文件夹等。我们建议参与配置或开发的所有人都从此处开始。

目录:

简介

项目和配置

      逐步发展您的工作室配置

      每个项目各有一个工作流配置

      检查更新

      检查核心 API 的更新

在磁盘上创建文件夹

当前上下文

文件系统模板

选择要运行的插件和应用

      默认配置中的环境

      Shotgun 中的环境 - 填充上下文菜单

配置应用

      挂钩

从 Shotgun 和 Shell 运行

发布到 Shotgun

构建可重用的应用

安全和身份认证

      升级至核心 v0.16

      身份认证和提示

            使用全局脚本密钥

            登录到 Shotgun

            在非交互式环境中运行

      技术细节

            Shotgun 身份认证库

            Shotgun 身份认证和权限

            Toolkit 序列化

            文件位置

            多线程环境

Toolkit 技术细节和延伸阅读

简介

想了解有关 Shotgun Pipeline Toolkit 的更多信息?这里就是您要找的地方!本文档将更深入地为您讲解一些主要功能。通过讲解、示例和简短的演示,我们将带您全面了解 Shotgun Toolkit。如果您想熟悉 Toolkit,或者想了解 Toolkit 如何为您的工作室带来价值,从本文档开始是个不错的选择。读完本文档后,您将很好地掌握一些主要概念以及它们在实践中的应用。

下面是有关 Shotgun Pipeline Toolkit (Sgtk) 的简介:

  • Sgtk 是一个基于 Shotgun 平台的“工作流工具包”- 通过它可以更轻松地为工作室编写和安装各种工具。
  • Sgtk 基于文件系统 - 它可以帮助您组织管理各种内容在磁盘上的存储,让磁盘内容井井有条。
  • Sgtk 是得力的助手 - 它并不会试图接管您工作流中的数据或对它们进行抽象,而是为美工人员提供强大的工具,帮助他们更轻松地查找信息和避免错误。
  • Sgtk 可帮助您共享 - Toolkit 会将所有发布内容存储在 Shotgun 中,让您很容易就能共享制作过程中持续进行的更新和工作。

在接下来的部分中,我们将深入了解 Shotgun Pipeline Toolkit 以及它的工作方式。

项目和配置

在 Shotgun Pipeline Toolkit 中,一切都以项目为中心。一个项目的生命周期通常始于 Shotgun 内,并经过投标和前期制作阶段。一旦项目准备好进入内容创作阶段,便可以为项目设置 Toolkit!

在设置新项目时,您需要使用模板配置。这是一个预先定义的配置,其中包含各种插件和应用、文件系统配置以及其他设置。如果您是刚刚开始接触 Toolkit,可以先使用我们的示例配置,以此为出发点开始探索。如果您已在另一个项目中使用 Toolkit,建议以那个项目的配置为基础开始新项目。这样,您将逐步形成并发展出一个工作室配置,然后针对每个新项目优化该配置。当然,也可以单独维护一个工作室配置,将它用作所有新项目的模板。

每个配置都定义了一些“存储点”。对于标准示例配置 tk-config-default,我们定义了一个称为“primary”的存储点。这意味着您的所有制作数据将位于一个文件系统项目根目录下。您也可以设置具有多个文件系统根目录的配置。我们将这类配置称为“多存储配置”。例如,当您为渲染和剪辑等内容分别设置了单独的存储时,就需要使用多存储配置。每个存储点在 Shotgun 中需要以“本地文件存储”的形式存在 - 您可以在“站点偏好设置”(Site Preferences)中的“文件管理”(File Management)选项卡下设置这些。

Shotgun Toolkit 会将实际的项目配置安装在您选择的任何位置,此位置通常是磁盘上的一个软件安装区域,而不是项目数据区域本身。(不用担心,如果您对位置不满意,稍后可随时移动它!)

逐步发展您的工作室配置

设置新项目时,您可以使用现有项目作为基础。Shotgun Toolkit 会将该项目的配置文件夹复制到您的新项目。这意味着,新项目将获得与它基于的项目完全相同的应用和插件版本、相同的设置和相同的自定义。如果您想逐步发展完善自己的工作流,并利用现有制作中所做的改进和调整,此功能非常有用。

或者,如果您对某个项目的设置满意,也可以直接选择该项目的配置文件夹,将它另存到别处的某个集中位置。随后可以将此配置用作工作室模板,每次创建新项目时以此配置为基础。如果需要,您甚至可以使用诸如 Git 等源代码控制工具控制此工作室模板配置的源代码,并能简单、透明地跟踪工作流配置模板如何随时间逐步完善。每当您想要更新模板时,只需复制一个项目的配置并提交更改即可。

有关配置管理的详细信息,请查看我们的详细文档:

每个项目各有一个工作流配置

每当您为项目设置 Shotgun Toolkit 时,都会创建一个工作流配置。此配置包含项目需要的所有设置和文件。配置有一个专用的 tank 命令,当您想直接处理该项目时,可以在 Shell 中运行此命令(另外还有一个适用于所有项目的全局 tank 命令)。在 Shotgun 中,工作流配置已注册为一个特殊的工作流配置实体,以易于跟踪项目配置在磁盘上的位置。

除了设置项目时创建的主配置外,您还可以为项目创建另外的配置。当您想更改配置但又不想影响项目的所有用户时,这种做法通常很有用。要创建另外的配置,可以在 Shotgun 中导航到一个工作流配置,然后单击鼠标右键选择克隆该配置即可。这将会基于另一个工作流配置为项目创建一个新配置。使用这个新配置,您可以在不影响其他用户的情况下安全地测试新应用等内容。

请注意,项目的主配置需要命名为 Primary。如果您重命名、修改或删除主配置,项目可能无法正常工作。Shotgun 中存储的工作流配置不支持手动操纵,需要通过各种特定的 tank 管理命令进行操纵,因此默认情况下是只读的。

示例:如何克隆配置

检查更新

与其他应用商店类似,Shotgun Toolkit 应用商店会经常发布新版本的应用和插件。这些新版本可能包含重要的错误修复或有趣的新功能。升级应用和插件并不是强制性的要求。这个过程通常很快,升级脚本在进行任何更改前都会提示您。同样,如果您意外安装了不满意的版本,回退也很简单直接。

一个命令控制整个升级过程。只需运行位于项目配置文件夹中的 tank 命令,并添加 updates 参数:

> /software/shotgun/bug_buck_bunny/tank updates

运行此命令时,如果不添加任何参数,将检查所有环境、插件和应用。这可能会花费很长时间。您也可以对其中一部分安装的应用和插件运行更新程序。

一般语法:

> tank updates [environment_name] [engine_name] [app_name]

可以使用特殊关键词 ALL 表示一个类别中的所有项。示例:

  • 检查所有内容:tank updates
  • 检查镜头环境:tank updates Shot
  • 检查所有环境中的所有 Maya 应用:tank updates ALL tk-maya
  • 检查镜头环境中的所有 Maya 应用:tank updates Shot tk-maya
  • 确保所有地方的加载器应用保持更新:tank updates ALL ALL tk-multi-loader
  • 确保 Maya 中的加载器应用保持更新:tank updates ALL tk-maya tk-multi-loader

除了检查应用商店,此脚本还会检查其他所有注册的位置。因此,它可能会查询您本地的 Git、GitHub 库、磁盘上的文件和应用商店,具体取决于各个应用的部署位置。

请注意,新版本的应用可能会引入应用配置方面的更改。例如,某项新功能可能会需要新的配置参数。这种情况下,tank 升级脚本会提示您键入这些参数的值。

检查核心 API 的更新

有时,我们会发布新版本的 Toolkit 核心 API。有一个单独的命令用来更新核心 API。在本例中,该命令为 tank core

在磁盘上创建文件夹

为项目设置 Shotgun Pipeline Toolkit 后,可以使用 Toolkit 帮助您创建一致的文件夹结构。可以通过在磁盘上的工作流配置中创建文件系统模板,来配置此文件夹结构。在此文件夹结构中,某些路径是动态路径。例如,您可以用一个名为 asset 的文件夹来表示 Shotgun 资产。这些动态文件夹可以与 Shotgun 查询和其他许多对象相连。

Shotgun Toolkit 提供多种不同类型的动态文件夹,用来应对不同的设置和情况。设置文件夹创建方式时,您可以使用标准 Shotgun API 查询语法。例如,您可以组织文件系统,将不同类型的资产归入文件系统上的不同文件夹。有关如何操作的详细介绍,请参见管理员手册:

Shotgun Pipeline Toolkit 的文件夹创建操作分为两个过程 - 一个是直接过程,任何人在任何时间都可以运行;另一个是延迟过程,通常由美工人员在应用程序临启动前运行。延迟过程完全自动,并可用来设置应用程序特定的文件夹和用户沙盒。

当前上下文

创建文件系统结构后,Shotgun Toolkit 会知道磁盘上文件夹与派生该文件夹的 Shotgun 对象之间的关系。这一点很重要,因为这样 Toolkit 才能很容易地在发布、加载或解析路径时将 Shotgun 中的对象与磁盘上的文件夹或文件相关联。另外,它还与我们所说的“上下文”或“当前工作区”有关。上下文对象是 Toolkit 核心的一部分,可跟踪记录当前正在处理的内容。它是 Toolkit 解析文件系统路径时的一个中枢机制(下文将对此予以介绍)。

我们可以从任务、资产或镜头等 Shotgun 对象创建上下文,也可以从磁盘路径创建上下文。应用在运行时始终可以访问上下文,这让构造应用变得很容易,您不需要了解文件系统的命名约定,也不必知道应用是用在资产工作流中还是镜头工作流中。所有这些全部由 Toolkit 核心 API 和上下文处理。

文件系统模板

Toolkit 核心包含一个处理文件路径的系统。我们称之为“模板系统”。由于 Shotgun Toolkit 基于文件系统,因此每当应用需要在磁盘上读取或写入数据时,都需要解析文件路径。应用对文件系统结构不了解 - 这意味着它们不知道文件系统的组织结构。模板系统负责为它们处理这一切。

在模板系统的核心,有一个模板配置文件。此文件包含项目的所有重要文件系统位置。模板与下面类似:

maya_shot_publish: 'shots/{Shot}/{Step}/pub/{name}.v{version}.ma'

模板本质上定义了一个包含一些动态字段的路径。每个字段都可以配置验证和键入内容,例如您可以定义上面模板中的 {version} 字段是一个填充三个零的整数(例如 001012132)。每当应用需要在磁盘上写入或读取数据时,都会向模板文件中添加一个描述该位置的模板。由于应用通常会构成一个工作流,因此一个应用(例如发布应用)的输出模板往往是另一个应用(例如加载应用)的输入模板。这就是所有文件系统位置都保留在一个文件内的原因。

模板 API 让您可以在一系列字段值和路径之间跳转:

# get a template object from the API
>>> template_obj = sgtk.templates["maya_shot_publish"]
<Sgtk Template maya_asset_project: shots/{Shot}/{Step}/pub/{name}.v{version}.ma>

# we can use the template object to turn a path into a set of fields...
>>> path = '/projects/bbb/shots/001_002/comp/pub/main_scene.v003.ma'
>>> fields = template_obj.get_fields(path)

{'Shot': '001_002',
 'Step': 'comp',
 'name': 'main_scene',
 'version': 3}

# alternatively, we can take a fields dictionary and make a path
>>> template_obj.apply_fields(fields)
'/projects/bbb/shots/001_002/comp/pub/main_scene.v003.ma'

注意上面的路径和模板如何有两个不同类型的字段:ShotStep 字段是高级别字段,在 Shotgun 中有对等的对象(一个镜头和一个工作流工序),其中 nameversion 字段是这种特定类型的模板所特有的(在本例中为发布路径)。如果我们想描述一个资产(而非镜头)的发布路径,仍然会有 nameversion 字段,因为这是所有发布都需要的,无论数据类型如何。但是,将不会有 ShotStep 字段。相反,可能会有 AssetStep 字段,其中的 asset 字段会与 Shotgun 中的某个资产相关联。

在开发用于发布类操作的应用时,很显然我们不想使用单独的应用分别执行镜头发布和资产发布。我们更希望开发一个可以应对任何发布情景的发布应用,无论要发布的是镜头序列、镜头、资产还是其他任何内容。

这时就需要用到 Toolkit 上下文。本质上讲,Toolkit 上下文让我们可以将模板字段分为两个不同的组(如上所述);上下文字段(ShotStepAsset 等)是我们想确保在应用外部解析的字段 - 这样应用代码就不必包含专门用于处理镜头和资产这类概念的代码。应用只需填充与应用的特定业务逻辑直接关联的字段。在我们的发布应用示例中,业务逻辑由 nameversion 字段组成。因此,如上图所示,Shotgun Toolkit 会将字段解析分为两个不同阶段:一些字段由上下文填充,另一些字段则由应用内部的业务逻辑填充。这样,应用的设计便可不局限于特定的文件系统布局。我们认为这是构建良好工作流工具的一个重要方面。

处理路径解析的应用代码通常如下所示:

# start with an empty fields dictionary
fields = {}

# first let the context populate all its fields
fields.update( self.context.as_template_fields( publish_template_obj ) )
# fields is now {'Shot': '001_002', 'Step': 'comp' }

# now the app can add its business logic
fields["name"] = "main_scene"
fields["version"] = 234

# and finally the app can produce the path it needs in
# order to save out the file
path = publish_template_obj.apply_fields(fields)

有关您可以如何配置和使用模板 API 的更多详细信息,请参见以下内容:

选择要运行的插件和应用

Toolkit 核心的另一个重要作用是决定应向用户显示哪些应用。如果您在处理角色装备工作并启动了 Maya,可能会需要一套与进行镜头照明工作时不同的应用。此外,应用的配置可能会因您需要的操作方式而异。因此,同一个审核应用,用于装备时可能会生成一个转台,而当动画设计师运行它时,则会使用镜头摄影机播放动画预览。

为了实现这种灵活性,Shotgun Toolkit 项目配置包含一系列“环境”。一个环境就是一个配置文件,用来定义一套应用和插件,以及它们的所有配置参数。

示例:环境文件的样子

环境文件是一个定义一系列插件和应用的 yaml 文件。

description: Example environment file

engines:

  tk-maya:
    debug_logging: false
    location: {name: tk-maya, type: app_store, version: v0.2.10}

    apps:

      tk-maya-breakdown:
        hook_multi_update: default
        hook_scan_scene: default
        location: {name: tk-maya-breakdown, type: app_store, version: v0.2.7}

      tk-multi-about:
        location: {name: tk-multi-about, type: app_store, version: v0.1.8}

      tk-multi-loader-1:
        dependency_mode: false
        hook_add_file_to_scene: default
        location: {name: tk-multi-loader, type: app_store, version: v0.2.6}
        menu_name: Load Assets...
        publish_filters: []
        sg_entity_types:
          Asset: []
        single_select: true
        tank_types: [Maya Model, Maya Rig]

  tk-nuke:
    debug_logging: false
    location: {name: tk-nuke, type: app_store, version: v0.2.10}

    apps:

      tk-multi-setframerange:
        location: {name: tk-multi-setframerange, type: app_store, version: v0.1.2}
        sg_in_frame_field: sg_cut_in
        sg_out_frame_field: sg_cut_out

      tk-multi-snapshot:
        hook_copy_file: default
        hook_scene_operation: default
        hook_thumbnail: default
        location: {name: tk-multi-snapshot, type: app_store, version: v0.1.15}
        template_snapshot: nuke_shot_snapshot
        template_work: nuke_shot_work

如您所见,每个应用和插件都有一个 location 参数。这个参数定义了代码的位置以及当前使用的版本。Toolkit 核心将使用此信息管理应用的更新检查。上面的示例显示了 app_store 类型的位置(例如来自包含已批准及精选应用的集中管理商店),但是我们还支持其他位置,例如 git。这让您可以轻松使用 Shotgun Pipeline Toolkit 随附的升级系统来管理和升级内部工具。

Toolkit 启动时,需要决定对哪个环境进行初始化。这通过一段称为“挂钩”的 Python 代码来实现,您可以在其中添加自己的业务逻辑。上下文对象(当前工作区)将传入这段代码中,它通常用来确定要使用哪个环境。

这样,您便可以为工作流的不同环节配置一组单独的应用。此外,您还可以独立更新它们,甚至安排不同的主管分别管理它们。

示例:选取环境挂钩的样子

选取环境挂钩可按项目进行自定义,下面就是一个示例。它位于 PIPELINE_CONFIG/core/hooks/pick_environment.py 中。

from tank import Hook

class PickEnvironment(Hook):

    def execute(self, context, **kwargs):
        """
        Example Pick Environment Hook!
        """

        if context.project is None:
            # our context is completely empty!
            # don't know how to handle this case.
            return None

        if context.entity is None:
            # we have a project but not an entity
            return "project"

        if context.entity and context.step:
            # we have a step and an entity
            if context.entity["type"] == "Shot":
                return "shot_step"
            if context.entity["type"] == "Asset":
                return "asset_step"

        return None

默认配置中的环境

为了给您一个实际示例来说明环境的工作方式和结构,我们来看一下默认配置随附的环境。

默认配置随附以下环境:

  • project.yml - 当上下文仅包含项目时要运行的应用和插件。
  • shot_and_asset.yml - 当上下文包含镜头或资产时要运行的应用和插件。
  • shot_step.yml - 当上下文包含镜头和工作流工序时要运行的应用和插件。
  • asset_step.yml - 当上下文包含资产和工作流工序时要运行的应用和插件。

默认配置基于工作流工序来组织其文件系统。举例来说,这意味着在某个镜头位置下,您可以看到针对建模和装备等的文件夹。实际上,您所执行的每个工作流工序都有一个对应的文件夹。每个文件夹在磁盘上都有自己的工作区和发布区。因此,发布模板可能如下所示:

maya_shot_publish: 'sequences/{Sequence}/{Shot}/{Step}/pub/{name}.v{version}.ma'

为了使用此模板,上下文需要同时包含一个实体(在本例中为镜头)和一个工作流工序。对于父镜头序列 ABC 下的镜头 1122 和 Modeling 这个工作流工序,上面的模板将解析为 sequences/ABC/1122/Modeling/...。这意味着,一个包含镜头但不包含工作流工序的上下文并不足以填充上面的模板。您无法为仅包含镜头的上下文启动 Maya 并使用上面的模板 - 为使该模板正常工作,必须有一个工序。

这样我们就得出了上面所示的环境细分。由于默认配置中定义的文件系统结构以工序为中心,因此所有主要应用都需要在一个定义了工序的上下文中运行。我们在默认配置中定义了两个这样的环境:asset_step.yml 文件和 shot_step.yml 文件。每个文件都包含针对多个 DCC(例如 Maya、Nuke、3ds Max、MotionBuilder、Photoshop 等)的插件。例如,当您从 Shotgun 内的镜头任务启动 Maya 时,选取环境挂钩将选择 shot_step 环境,启动 Maya 并加载 Maya 应用配置。

有时候,直接从 Shotgun 内的镜头对象启动 Maya 也是有用的。更重要的是,能在控制台中键入 tank Shot 1122 launch_maya 真的是一项非常实用的功能。这种情况下,就要用到 shot_and_asset 环境。当您为 Maya 加载一个包含镜头(或资产)但不包含工作流工序的上下文时,它将会加载此环境。但是,由于文件系统结构都是按工作流工序进行组织,因此如果我们只有镜头的话,实际上不太可能执行任何加载或发布操作。Maya 会使用一个空配置启动,其中仅包含“工作文件”应用。此应用让您可以选择要处理的任务,然后将上下文切换至此任务。选取任务后,Toolkit 会为您切换上下文并重新启动插件,还会为 shot_step 环境加载全套应用。

同样,project 环境是一个适合所有情况的备选方案,它也只包含“工作文件”应用。这使您几乎可以从项目内的任何地方启动 Maya(或其他应用),它会对 Toolkit 进行最小程度的初始化,让您可以使用“工作文件”应用跳转到有效的工作区。

Shotgun 中的环境 - 填充上下文菜单

除了上面介绍的由 Shotgun Pipeline Toolkit 根据上下文自动选择的动态环境外,Toolkit 还附带一组特殊的 Shotgun 环境。这些环境控制着 Shotgun 内的上下文菜单上显示哪些应用。所有这些环境文件均以 shotgun_entitytype.yml 的形式命名,例如 shotgun_shot.ymlshotgun_asset.yml。您在这些环境中定义的任何应用,都将显示在 Shotgun 中该实体类型的上下文菜单上。

配置应用

每个应用都有一些需要指定的配置参数。当您安装或升级某个应用时,Toolkit 会确保您指定了所有必需的设置。设置通常会自动记录 - 请转到文档的“应用列表”部分查看一些示例:

简单的设置值(如字符串和整数值)直接在环境配置中指定。模板各不相同。由于 Shotgun Toolkit 要将所有模板保存在一处,因此环境文件只是指向模板文件中定义的模板。每个应用在其配置中使用的模板需要的字段各不相同。例如,在前面的示例中,示例发布应用在磁盘上创建输出文件时,使用一个包含 nameversion 字段的模板。因此,此应用的一项配置设置就需要使用包含 nameversion 字段的模板。

如果您配置应用时尝试使用的模板包含比 nameversion 更多的上下文字段,应用代码将不知道如何填充这些额外的字段,因此将无法根据该模板生成路径。同样,如果您提供的模板缺少其中某个字段(例如 version),会导致结果混淆。在我们的示例中,将不会为应用写出版本号。因此,Toolkit 会在启动时验证配置,确保您为所有模板提供了必要的字段。Shotgun Toolkit 还支持几种使用默认值和可选字段的方式。有关完整参考,请查看以下链接:

挂钩

除了使用模板的应用设置外,Shotgun Pipeline Toolkit 还支持称为“挂钩”的概念。挂钩是小段的 Python 代码片段,实际上让您可以在配置中自定义应用代码的各个部分。下面我们来介绍它是如何工作的,以及为什么它非常有用。

应用之所以强大,是因为它们可以在多个插件和项目中重复使用。但是,应用往往需要一些特定于插件的小段代码。例如,如果我们要构建一个可同时在 Nuke 和 Maya 中运行的加载器应用,就需要有处理实际文件加载操作的代码 - 而这些代码在 Nuke 和 Maya 中必然是不同的,因为它们的 API 截然不同。不仅如此,我们还希望此应用最好能用于任何插件!另外,不同工作室向场景中加载内容项的方式也有所不同 - 有些工作室可能需要支持自定义的 Maya 引用节点,有些则只要执行导入即可。

在 Toolkit 中,这种情况可以使用“挂钩”来解决。挂钩是一段可自定义的代码。应用随附一个默认挂钩,其中包含一个基础执行,这意味着应用可以开箱即用。但是,如果您想自定义行为,可以将默认挂钩文件复制到您的配置中,Toolkit 会改为使用该代码。

从 Shotgun 和 Shell 运行

安装 Shotgun Toolkit 之后,您可以从几个主要的入口点访问它:

  • Shotgun 内的右键单击菜单上将显示 Shotgun 动作
  • Shotgun Desktop 应用中的项目将显示启动图标
  • 您可以在控制台中使用 tank 命令。
  • 在应用程序内和 Shell 中均可使用 Toolkit 的 Python API。

从 Shotgun 内运行 Toolkit 是一种启动应用程序和执行任务的常见方式。Shotgun Toolkit 将使用 Shotgun 浏览器插件与计算机本地安装的 Toolkit 通信,并使用本地 Python 执行 Shotgun 插件和应用。这意味着您可以直接从 Shotgun 内运行创建文件夹等本地操作。另外,还可以从 Shotgun 内执行基于 QT 用户界面的应用。

您还可以从命令 Shell 访问 Shotgun Toolkit。每个项目配置随附属于自己的 tank 命令。您只需导航到项目配置的根目录,在其中执行 ./tank 命令即可。

最后,您可以直接将 Toolkit API 添加到 PYTHONPATH,然后将其导入。使用 API 非常简单直接。例如,如果您想在 Maya 内手动启动 Shotgun Pipeline Toolkit,或者想将它作为现有工作室启动系统的一部分,那么可以不使用启动器应用工具,只需执行几个简单的命令即可。

发布到 Shotgun

当您想与其他人共享自己正在处理的文件时,可以发布这些文件。这意味着会在 Shotgun 内创建一个发布记录。

这种做法对于数据管理(数据在磁盘上的存储位置、文件包含的内容等)到底意味着什么,交给处理实际工作的应用去考虑。Toolkit API 为应用开发人员提供了各种方法,让他们可以轻松在 Shotgun 内创建发布,并将这些发布链接到正确的对象,以确保 Shotgun 可以直接将通知推送给所有合适的人员。我们还提供一个默认的发布应用,它不仅功能灵活多样,而且可配置程度很高,但这并不是使用 Shotgun Toolkit 执行版本控制的唯一途径。因为 Sgtk 是一个工作流工具包,所以如果需要,您可以使用 Toolkit 打造自己的自定义版本控制和发布系统。但是一开始,建议您使用我们的发布应用:

构建可重用的应用

Shotgun Pipeline Toolkit 不止是一套应用和插件。它还是一个框架,您可以用它开发自己的工具和技术!我们已在 Shotgun Toolkit 中包含了大量功能,将它打造成一个功能丰富的工作室开发平台。有了 Toolkit 作为基础,您可以专注于解决手中的问题,而不必花费精力构建底层的工作流堆栈。我们努力让开发人员可以在不意外打断美工人员工作流的前提下轻松构建、评估和发布软件。

  • 插件将确保无论底层基础是什么,开发人员都可以使用 Python 和 QT (PySide/PyQt) 编写应用。这意味着,有些插件非常简单(例如 Nuke 插件,因为 Nuke 已包含了 PySide 和 Python),有些插件则更复杂(例如 Photoshop 插件,因为 Photoshop 不支持 Python)。因此,工作室有一种直观、一致的方式来开发工具。根据我们的经验,Python 和 PyQt/PySide 是工作室常用的开发环境,许多技术总监都熟悉它们。

  • 插件层还有一个好处,那就是应用只需编写一次,便可在多种环境中部署。我们将开发的标准应用套件称为多应用,意思是同一个应用适用于所有插件。当然,难免会有些特定的代码需要定制后才能用于每个 DCC 应用程序公开的特定 API,但是这些代码通常包含在一个或多个挂钩中,这让重用应用变得很简单。能够创建这种多应用的另一个好处是,在开发新插件的过程中,很容易就可以配置所有标准应用来支持新插件。

  • 通过工作流配置和克隆,我们可以轻松创建开发沙盒,让开发人员能够在制作环境中进行开发,同时又不会干扰日常的制作活动。工具做好部署准备后,轻松即可更新主项目配置,然后将工具部署给所有美工人员。

  • 应用在插件内运行,因此重新加载很容易。不必每次测试新的代码更改时都重新启动 Nuke 或 Maya,只需单击 Toolkit 中的重新加载按钮,即可加载最新代码。

有关应用开发方面的更详尽介绍,请参见以下文档:

安全性和身份认证

当您运行 Shotgun Pipeline Toolkit 时,它会定期连接到 Shotgun 执行某些操作。比如当您发布新的渲染时,或者浏览某个想要加载到场景中的内容项时。这时,Toolkit 需要登录到 Shotgun 以读取或写入数据,这意味着它需要确保当前用户通过身份认证,才能够与 Shotgun 服务器建立连接。

在 v0.16 之前的 Toolkit 核心版本中,这是通过使用一个 Shotgun API 脚本用户执行所有 Toolkit 操作的方式来自动完成的。在核心版本 v0.16 中,Toolkit 使用的默认模式要求每个用户提供登录名和密码,交互体验因此变得与 Shotgun 其余环节类似。

Toolkit 使用会话令牌进行身份认证。这些会话令牌是 Shotgun 服务器生成的唯一标识符。每当 Toolkit 发来 Shotgun API 请求时,会随之传递此会话令牌,让服务器可以验证它并授予请求访问权限。这些会话令牌会在一段时间(通常是 24 小时)不活动后超时。每当令牌超时,通常会提示用户重新输入密码,以便 Toolkit 重新取得新的会话令牌。

在一个工作流中,有时很难甚至根本不可能提示用户输入密码,这种情况并不少见。针对这些情况,Toolkit 提供了几种方式,让您完全“不加思考”地运行或完全自定义身份认证相关的流程。下面这个小节概述了 Toolkit 安全模型如何工作,以及我们可以对它进行怎样的自定义。

升级至核心 v0.16

在 v0.16 之前,所有身份认证都是通过一个称为 shotgun.yml 的配置文件来完成,该配置文件包含 Shotgun 脚本凭据,让所有用户不必登录就能以相同的方式访问 Shotgun。核心 v0.16 仍然支持此行为,但是默认会提示用户输入用户名和密码,这让 Toolkit 可以更精细地控制其用户,并避免在全局位置存储脚本凭据。

核心 v0.16 完全向后兼容,并且只要遇到在 shotgun.yml 文件中指定了脚本凭据的 Toolkit 项目,就会使用这些凭据进行身份认证。这意味着,当您更新至 Toolkit 核心 v0.16 时,现有项目并不会受新身份认证功能的影响。

现有的 shotgun.yml 文件通常如下所示:

# Shotgun Pipeline Toolkit configuration file
# this file was automatically created

host: https://mysite.shotgunstudio.com
api_key: abcdefghijklmnopqrstuvwxyz01234567890ABCDE
api_script: Toolkit
http_proxy: null

# End of file.

如果移除 api_scriptapi_key 行,Toolkit 将开始提示用户输入登录名和密码。当您在 v0.16 中设置新项目时,它们将自动使用以下格式:

# Core v0.16 example which doesn't store script
# credentials in a file but instead prompts each
# user to individually log in

host: https://mysite.shotgunstudio.com
http_proxy: null

# End of file.
  • 如果您想让现有项目能够运行核心 v0.16 中引入的新身份认证功能,只需找到它的 shotgun.yml 文件(通常位于配置文件夹的 config/core 中),注释掉 api_keyapi_script 键即可。

  • 相反,如果您创建了一个新项目,想使用 Toolkit 中之前使用的自动身份认证模型,只需为 shotgun.yml 更新有效的脚本凭据即可。

  • 请注意,注释掉现有项目的 api_keyapi_script 字段意味着配置将不再支持 v0.16 之前版本的核心。在这样做之前,请确保所有参与该项目的用户都已升级至核心 v0.16。

  • 高级用户及类似上述情况的用户注意:如果您运行的是 Shotgun Desktop v1.0.x,请不要手动从 Shotgun Desktop 使用的本地站点配置中移除 api_keyapi_script 字段。虽然早期 v1.0.x 版本的 Shotgun Desktop 能够处理未在 shotgun.yml 文件中存储脚本凭据的项目,但是其站点配置文件中仍需要有这些字段。要完全消除工作流中硬编码的凭据,您需要更新至最新版本的 Shotgun Desktop。

  • 如果您的项目使用的是共享核心,shotgun.yml 文件将位于核心配置位置,而不是项目配置位置。如果是这样,您所做的任何更改将影响所有使用该核心的项目。

  • 不匹配用户登录名 - 之前,每个用户会使用同一个脚本用户连接到 Shotgun,这意味着 Shotgun 连接对于实际连接的是哪个用户没有很强的概念。Toolkit 会尝试获取当前用户的操作系统登录名(使用挂钩),并将它与 Shotgun 中的用户进行匹配,通过这种方法确定当前用户实际是谁。此行为在 v0.16 中作为一项回退机制仍然存在,但是对于所有已启用了按用户进行身份认证功能的新项目来说,这种系统登录名匹配逻辑已不再需要,也不会再使用。

  • 新的权限 - 之前,当 Toolkit 只使用一个 Toolkit 脚本用户进行连接时,与此脚本用户关联的 Shotgun 权限将是决定 Shotgun 内可以执行哪些操作的一个限制因素。而在新项目中,用户开始改为自己登录 Toolkit,这时用户的 Shotgun 权限将决定他们可以执行哪些操作。这可能会影响到操作的行为 - 无论对于内部工具还是自定义功能都是如此。过去 Toolkit 脚本用户会代表美工人员执行 Shotgun 操作,现在则是美工人员使用自己的凭据执行相同的操作。通过调整用户的 Shotgun 权限,确保他们有权限执行所有必要的工作流操作,往往可以快速修复潜在的问题。

身份认证和提示

自 Toolkit 核心 v0.16 起,现在支持几种不同的安全模式,下文对所有模式进行了介绍。

使用全局脚本密钥

如果您不希望提示任何用户输入他们的登录名和密码,可以在 shotgun.yml 文件中指定一个全局 Shotgun 脚本密钥。Toolkit 将为所有 Shotgun 操作使用此密钥。这是在 Toolkit 核心 v0.16 之前所有项目使用的安全模式。默认情况下,创建新项目时不会使用此全局脚本密钥,但是您可以通过向 shotgun.yml 中添加 api_scriptapi_key 选项来启用它。有关示例,请参见文档的上一小节。

登录到 Shotgun

在基于用户的安全模式下运行时,Shotgun 将需要您提供登录名和密码,以验证您的身份。它会在不同会话中记住这些信息,但可能会偶尔要求您输入登录名和密码。

当您登录到 Toolkit 时,您的密码会以安全的方式发送至 Shotgun 服务器,服务器会返回一个会话令牌。然后,Toolkit 会使用此令牌进行连接,并且在令牌有效期间,不会再要求您提供密码。令牌在一段时间后(通常为 24 小时不活动后)会过期,然后 Toolkit 会再次要求您提供密码。Toolkit 可能会在几个不同的地方提示您输入登录名和/或密码:

  • 当您启动 Shotgun Desktop 时。

  • 当您在终端中运行 tank 命令时。有几种方法可以关闭此提示 - 下节对此进行了介绍。

  • 当您在 Shotgun Web 应用程序中单击 Toolkit 动作菜单项时。

  • 通常,当您启动 Maya、Nuke 或其他 DCC 时,并不会提示您输入密码。这是因为 Shotgun Desktop、Shotgun Web 应用程序或 tank 命令已刷新了您的身份认证。但是,如果让 Maya 或 Nuke 保持打开且不活动超过 24 小时,它可能会显示一个对话框,要求您重新输入密码。这将发生在 Toolkit 需要访问 Shotgun 之前。

在非交互式环境中运行

很多时候,工作流的代码需要在没有用户界面或用户的环境中执行。在渲染农场上执行代码就是一个典型的例子。针对这种使用情况,Toolkit 提供了几种方法,通过 API 和命令行提供凭据。

如果您使用 tank 命令,有几个选项可以使用。您可以直接通过 --script-name--script-key 命令行参数提供脚本名称和脚本密钥来进行身份认证:

# never prompt for a username or password
> tank --script-name=headless_launcher --script-key=xxx Shot ABC123 launch_maya

如果不想直接在命令行中提供详细信息,也可以将它们存储在一个文件中,然后通过 --credentials-file 参数将 tank 命令指向此文件:

# never prompt for a username or password
> tank --credentials-file=/path/to/script_credentials.yml Shot ABC123 launch_maya

此文件应采取以下形式:

script-name: Toolkit
script-key: abcdefghijklmnopqrstuvwxyz01234567890ABCDE

这样,就可以维护多个 Shotgun 脚本用户,每个用户拥有不同的权限设置,适用于一种不同的工作流服务,从而确保您的流程仅对它们需要的 Shotgun 数据拥有有限的访问权限。

如果您直接使用 Toolkit API,目前必须编写一些代码来确保 Toolkit 通过身份认证。Sgtk API 中主要的安全 API 方法是 sgtk.set_authenticated_user(user),您可以使用它将特定用户与 Toolkit 核心会话相关联。传递给此方法的用户对象由 Shotgun 身份认证 API 生成,后者会抽象出关于身份认证的逻辑。下面的示例代码说明了如何设置一个使用 Shotgun 脚本进行身份认证的 Toolkit 核心 API 会话:

import sgtk
from tank_vendor.shotgun_authentication import ShotgunAuthenticator

# create an authenticator object. This is the main object which
# handles all authentication
sa = ShotgunAuthenticator()

# Use the authenticator to create a user object. This object
# identifies a Shotgun user or script and also wraps around
# a Shotgun API instance which is associated with that user.
user = sa.create_script_user(api_script="myscript",
                             api_key="xxxxx",
                             host="https://myhost.shotgunstudio.com")

# tell the Toolkit Core API which user to use
sgtk.set_authenticated_user(user)

在 Toolkit 中设置了通过身份认证的用户后,用户对象会作为 context 序列化方法的一部分自动进行序列化。这意味着,当您启动例如 Maya、Nuke 或其他 DCC 时,凭据会从启动进程(通常为 tank 命令、Shotgun Desktop 或 Shotgun Web 应用程序)传递至启动的 DCC。这样就可以很轻松地将有效凭据从一个进程传递给另一个进程。

有关 Shotgun 认证器 API 的详细信息,请参见内嵌代码文档。

技术细节

Shotgun 身份认证库

我们已将所有与 Shotgun 相关的身份认证逻辑开发成一个独立的 Python 库,供 Toolkit 核心和 Shotgun Desktop 使用。其他(非 Toolkit)应用程序如果需要处理要求用户登录 Shotgun 的使用情景,也可以使用这个库。这个库封装了 Shotgun API,并包含一个基于 QT 的标准化 Shotgun 登录对话框,当用户需要进行身份认证时,会显示此对话框。Shotgun 身份认证模块可处理许多有关 Shotgun 身份认证的常见情况,并有助于打造标准化的用户体验,确保用户使用起来安全轻松。功能集摘要:

  • 在提示输入用户名和密码方面,提供一种标准化的基于 QT 和命令行的用户体验。

  • 默认在不同 API 实例中提供持久性 Shotgun 会话令牌机制,让 API 尽可能减少对用户的干扰。

  • 提供可配置、可改写的默认设置管理器,让 API 客户端可以配置默认值的行为。

  • API 中心设有一个 Shotgun 认证器实例,充当 Shotgun 用户对象的工厂。这些对象在 Shotgun 中代表用户或脚本。

  • 身份认证库返回的 Shotgun 用户对象具有一个 create_sg_connection() 方法,该方法将创建一个与该用户关联的 Shotgun API 实例。对于非脚本用户,Shotgun API 实例使用的会话令牌通常会在 24 小时不活动之后变得无效。在这种情况下,Shotgun API 实例将过滤此错误,并自动提示用户键入密码。

有关更多详细信息,请参见 Shotgun 身份认证模块的内嵌代码文档。

Shotgun 身份认证和权限

每当用户在 Toolkit 中使用其登录名和密码进行身份认证时,Shotgun 身份认证库会连接 Shotgun 服务器,以此信息交换会话令牌,然后使用该令牌提交后续请求。密码不存储在任何位置,会话令牌则存储在磁盘上的一个文件权限受限的文件中,供每次需要进行身份认证时使用。Toolkit 会尽可能尝试使用此保存的会话令牌,并且仅当令牌不再有效时才提示用户。令牌通常会在 24 小时不活动之后失效。

当 Toolkit 以这种方式与 Shotgun 通信时,API 会话将使用与用户登录到 Shotgun Web 应用程序后正常具有的相同 Shotgun 权限规则。请注意,这些权限可能与默认的 Shotgun API 脚本权限不同,并且通常限制更多,这意味着有些操作在以脚本用户身份登录时可以执行,但在以用户身份登录时可能会失败,反之亦然。如果您遇到权限错误,请在 Shotgun 权限编辑器中重新核对您的用户及 API 脚本的权限。您可以在 Shotgun Web 应用程序的管理员菜单中找到此编辑器。

Toolkit 序列化

当您在 Toolkit 中启动了诸如 Maya 或 Nuke 的 DCC 时(使用 tk-multi-launchapp),当前的 context 通常会序列化为一种基于字符串的形式。然后,DCC 进程将启动,并且通常会按要求执行 Toolkit 提供的启动或引导脚本。此脚本会将上下文字符串反序列化为一个对象,创建一个新的 tk 实例,最后启动插件。

在这个过程中,用户对象也将被序列化,这意味着新进程在运行时将使用与父进程完全相同的凭据设置。这样,就可以很容易为不同用户启动不同进程,或在一台计算机上捕捉上下文,然后在另一台计算机上执行该上下文等等。

文件位置

会话令牌存储在以下文件中:

  • ~/Library/Caches/Shotgun/SITENAME/authentication.yml (Mac OSX)
  • ~/.Shotgun/SITENAME/authentication.yml (Linux)
  • %APPDATA%/Shotgun/SITENAME/authentication.yml (Windows)

Toolkit 身份认证库保留了当前站点和当前用户的概念,这意味着可以使用此库保持单点登录,让所有应用程序和会话可以访问同一登录凭据。

多线程环境

一段时间不活动后,会话令牌会过期,这时 Shotgun 身份认证库会提示用户输入密码。与登录时一样,此密码将发送至 Shotgun 服务器,用来换取新的有效会话令牌。

更具实际意义的是,Shotgun 身份认证库的 user_object.create_sg_connection() 方法返回的 Shotgun API 句柄还包含用来检查会话是否过期的封装器代码。只要检测到会话过期,就会提示用户重新进行身份认证,并重试操作。

在多线程情况下,多个工作线程都在运行 Shotgun API 实例,当多个线程同时遇到会话过期时,Shotgun 身份认证库会暂停除第一个线程以外的所有线程,并使用此线程提示用户输入新密码。这样做是为了避免用户一次又一次收到提示。每当用户收到提示时,主线程中总是会执行 QT 用户界面代码。

Toolkit 技术细节和延伸阅读

Shotgun Pipeline Toolkit 使用 Python(v2.6+ 但不是 3.x)编写,实质上是在客户端计算机上执行的一系列脚本。Toolkit 适用于 Linux、Windows 和 Mac OSX 平台。

大多数资产管理系统都有一个数据库用来存储元数据。Toolkit 并没有自己的数据库,而是使用 Shotgun 的数据库存储数据和管理上下文。核心 API 中的大部分操作使用文件系统来解析路径和数据,而不是与 Shotgun 进行通信。

核心 API 不会试图“掌控全局”,也不是“要么全管、要么不管”。相反,它会在一旁尝试为脚本和美工人员提供建议和协助。我们常见的一种资产管理做法是试图全面掌控文件系统和工作流中的数据流。通过了解工作流中发生的一切,系统可以非常精确地跟踪内容的创作和处理。但是,这种做法需要付出代价 - 完全掌控往往意味着需要重新编写现有的所有工具,并会引入一个所有数据都需要流经的中心点。尽管这种做法有时很好,但是 Toolkit 并不试图掌握数据。而是尝试着了解数据,并在一旁提供帮助。Shotgun Toolkit 知道应将数据存储在磁盘的什么位置,这让美工人员和开发人员可以轻松开展协作,有组织地完成整个制作过程。

您可以将 Shotgun Toolkit 与现有的工作流设置和内容跟踪系统一起运行。只要它们就数据在磁盘上的位置达成共识,Toolkit 就应该能够与它们交换数据。

有关更多深入的信息,请参见以下文档:

动画电影“Big Buck Bunny”(大雄兔)由 (CC) Blender Foundation (www.blender.org) 提供
关注

0 评论

登录写评论。