设置 Openflow Connector for Jira Cloud¶

备注

This connector is subject to the Snowflake Connector Terms.

本主题介绍设置 Openflow Connector for Jira Cloud 的步骤。

先决条件¶

确保您已查看关于 Openflow Connector for Jira Cloud。
Ensure that you have 设置 Openflow - BYOC or Set up Openflow - Snowflake Deployments.
If using Openflow - Snowflake Deployments, ensure that you've reviewed configuring required domains and have granted access to the required domains for the Jira Cloud connector.

获取凭据¶

作为 Jira Cloud 管理员，在您的 Atlassian 账户中执行以下任务：

导航到 API 令牌页面 (https://id.atlassian.com/manage-profile/security/api-tokens)。
选择 Create API token with scopes。
在 Create an API token 对话框中，提供 API 令牌的描述性名称，然后选择 API 令牌的有效期。范围为 1 到 365 天不等。
选择 Api 令牌应用程序 Jira。
选择 jira 范围 read:jira-work 和 read:jira-user。
选择 Create token。
在 Copy your API token 对话框中，选择 Copy 复制生成的 API 令牌，然后将令牌粘贴到连接器参数中，或者将其安全保存下来。
选择 Close 以关闭对话框。

设置 Snowflake 账户¶

作为 Snowflake 账户管理员，执行以下任务：

创建新角色或使用现有角色。
创建一个类型为 SERVICE 的新 Snowflake 服务用户。
向该 Snowflake 服务用户授予您在前面步骤中创建的角色。
为第 2 步中创建的 Snowflake SERVICE 用户配置密钥对身份验证。
Snowflake 强烈建议执行此步骤。配置 Openflow 支持的密钥管理器（例如 AWS、Azure 和 Hashicorp），并将公钥和私钥存储在密钥存储库中。

备注

如果您出于任何原因不希望使用密钥管理器，则您有责任根据组织的安全策略保护用于密钥对身份验证的公钥和私钥文件。
1. 配置密钥管理器后，确定如何对其进行身份验证。在 AWS 中，建议您使用与 Openflow 关联的 EC2 实例角色，因为这样就无需保留其他密钥。
2. In Openflow, configure a Parameter Provider associated with this Secrets Manager, from the hamburger menu in the upper right. Navigate to Controller Settings » Parameter Provider and then fetch your parameter values.
3. 此时，可以使用关联的参数路径引用所有凭据，无需在 Openflow 中保留敏感值。
如果任何其他 Snowflake 用户需要访问连接器引入的原始文档和表（例如，在 Snowflake 中进行自定义处理），则授予这些用户在步骤 1 中创建的角色。

在 Snowflake 中为连接器创建数据库和架构，以存储引入的数据。向第一步中创建的角色授予以下数据库权限权限。

CREATE DATABASE jira_destination_db;
CREATE SCHEMA jira_destination_db.jira_destination_schema;
GRANT USAGE ON DATABASE jira_destination_db TO ROLE <jira_connector_role>;
GRANT USAGE ON SCHEMA jira_destination_db.jira_destination_schema TO ROLE <jira_connector_role>;
GRANT CREATE TABLE, CREATE VIEW ON SCHEMA jira_destination_db.jira_destination_schema TO ROLE <jira_connector_role>;

Copy

创建供连接器使用的仓库，或者使用现有仓库。从最小的仓库规模开始，然后根据要复制的表数量和传输的数据量来测试规模。相较于扩大仓库规模，采用多集群仓库通常能更有效地应对海量表数量的扩展需求。

确保具有连接器所用角色的用户具备使用仓库所需的权限。否则请向该角色授予所需权限。

CREATE WAREHOUSE jira_connector_warehouse WITH WAREHOUSE_SIZE = 'X-Small';
GRANT USAGE ON WAREHOUSE jira_connector_warehouse TO ROLE <jira_connector_role>;

Copy

设置连接器¶

作为数据工程师，执行以下任务以安装和配置连接器：

安装连接器¶

Navigate to the Openflow overview page. In the Featured connectors section, select View more connectors.
在 Openflow 连接器页面上，找到连接器并选择 Add to runtime。
In the Select runtime dialog, select your runtime from the Available runtimes drop-down list and click Add.

备注

在安装连接器之前，请确保在 Snowflake 中为连接器创建了数据库和架构，用于存储引入的数据。
使用您的 Snowflake 账户凭据对部署进行身份验证，并在系统提示时选择 Allow，以允许运行时应用程序访问您的 Snowflake 账户。连接器安装过程需要几分钟才能完成。
使用您的 Snowflake 账户凭据进行运行时身份验证。

此时将显示 Openflow 画布，其中添加了连接器进程组。

配置连接器¶

右键点击导入的进程组并选择 Parameters。
按照流参数中所述填充所需的参数值。

流参数¶

本节介绍您可以根据以下参数上下文配置的流参数：

Jira Cloud 源参数：用于与 Jira API 建立连接。
Jira Cloud 目标参数：用于与 Snowflake 建立连接。
Jira Cloud 引入参数：用于定义从 Jira 下载的数据的配置。

备注

修改与引入配置相关的参数（例如，“Search Type”、“JQL Query”、“Project Names”和“Created After”）将重置 FetchJiraIssues 处理器的状态，使其能够再次提取所有问题。当您需要修改问题查询条件或希望从头重新启动引入时，此功能非常有用。此重置操作不会截断目标表。

Jira Cloud 源参数¶

参数	描述
Jira 电子邮件	Atlassian 账户对应的电子邮件地址。
Jira API Token	用于您 Atlassian Jira 账户的 API 访问令牌，需包含必要的作用域（`read:jira-work` 和 `read:jira-user`）。
环境 URL	Atlassian Jira 环境的 URL。例如 `https://your-domain.atlassian.net`。

Jira Cloud 目标参数¶

参数	描述	必填
目标数据库	The database where data will be persisted. It must already exist in Snowflake. The name is case-sensitive. For unquoted identifiers, provide the name in uppercase.	是
目标架构	The schema where data will be persisted, which must already exist in Snowflake. The name is case-sensitive. For unquoted identifiers, provide the name in uppercase. 请参阅以下示例： `CREATE SCHEMA SCHEMA_NAME` 或 `CREATE SCHEMA schema_name`：使用 `SCHEMA_NAME` `CREATE SCHEMA "schema_name"` 或 `CREATE SCHEMA "SCHEMA_NAME"`：分别使用 `schema_name` 或 `SCHEMA_NAME`	是
Snowflake 身份验证策略	使用以下方式时： Snowflake Openflow Deployment or BYOC: Use SNOWFLAKE_SESSION_TOKEN. This token is managed automatically by Snowflake. BYOC deployments must have previously configured runtime roles to use SNOWFLAKE_SESSION_TOKEN. BYOC: Alternatively BYOC can use KEY_PAIR as the value for authentication strategy.	是
Snowflake 账户标识符	使用以下方式时： Session Token Authentication Strategy: Must be blank. KEY_PAIR: Snowflake account name formatted as [organization-name]-[account-name] where data will be persisted.	是
Snowflake 私钥	使用以下方式时： Session Token Authentication Strategy: Must be blank. KEY_PAIR：必须是用于身份验证的 RSA 私钥。 The RSA key must be formatted according to PKCS8 standards and have standard PEM headers and footers. Note that either a Snowflake Private Key File or a Snowflake Private Key must be defined.	否
Snowflake 私钥文件	使用以下方式时：会话令牌身份验证策略：私钥文件必须为空。 KEY_PAIR: Upload the file that contains the RSA private key used for authentication to Snowflake, formatted according to PKCS8 standards and including standard PEM headers and footers. The header line begins with `-----BEGIN PRIVATE`. To upload the private key file, select the Reference asset checkbox.	否
Snowflake 私钥密码	使用以下方式时： Session Token Authentication Strategy: Must be blank. KEY_PAIR: Provide the password associated with the Snowflake private key file.	否
Snowflake 角色	使用以下方式时： Session Token Authentication Strategy: Use your runtime role. You can find your runtime role in the Openflow UI, by navigating to View Details for your Runtime. KEY_PAIR 身份验证策略：使用为您的服务用户配置的有效角色。	是
Snowflake 用户名	使用以下方式时： Session Token Authentication Strategy: Must be blank. KEY_PAIR: Provide the user name used to connect to the Snowflake instance.	是
Snowflake 仓库	Snowflake warehouse used to run queries.	是

Jira Cloud 引入参数¶

参数	描述
搜索类型	要执行的搜索类型。它具有以下可能的值之一：`SIMPLE` 和 `JQL`。默认值：`SIMPLE`。
目标表	存储数据的 Snowflake 表。如果该表不存在，则系统会创建它。表的名称不得加引号，并且必须以大写形式提供。除目标表外，还会创建基于目标表的扁平化视图。视图名称是表名和后缀 `_VIEW` 的组合
JQL 查询	用于搜索要提取的 Jira 问题的 JQL 查询。应该仅在“Search Type”为 `JQL` 时使用。
项目名称	应从中提取问题的项目列表。您可以按项目名称、项目关键字或项目 ID 搜索属于一个特定项目的问题。应该仅在“Search Type”为 `SIMPLE` 时使用。提供以逗号分隔的项目列表。例如：`Project1, Project2`。
状态类别	用于简单搜索的状态类别筛选器。应该仅在“Search Type”为 `SIMPLE` 时使用。示例值：`Done`、`In Progress`、`To Do`。
之后更新	筛选在指定日期和时间后更新的问题。应该仅在“Search Type”为 `SIMPLE` 时使用。它应该采用 yyyy-MM-dd 格式，例如 2023-10-01。
之后创建	筛选在指定日期和时间后创建的问题。应该仅在“Search Type”为 `SIMPLE` 时使用。它应该采用 yyyy-MM-dd 格式，例如 2023-10-01。
问题字段	每个问题要返回的字段列表，用于检索字段子集。自定义字段的 IDs 可通过遵循本指南 (https://confluence.atlassian.com/jirakb/get-custom-field-ids-for-jira-and-jira-service-management-744522503.html) 获取。此参数接受逗号分隔式列表。您可以使用特殊值：使用 `all` 可提取所有字段，使用 `navigable` 可提取可导航字段，为字段加上减号前缀 (`-`) 可排除字段。例如，`all,-description` 返回除描述之外的所有字段。默认值：`all`。
Fetch All Worklogs	Determines whether to fetch all worklogs for each issue. Default value: `false`. When set to `true`, the connector enriches issues with all associated worklogs, beyond the default 20 worklogs per issue returned by the Jira Cloud REST API. When set to `false`, only the first 20 worklogs per issue are fetched. 备注 Setting this parameter to `true` can impact performance due to the increased number of API calls required to fetch all worklogs for issues with more than 20 worklogs.
最大页面大小	每个请求返回的最大问题数，默认值和最大值为 `1000`。请注意，根据响应总大小，Jira API 返回的结果可能会更少。

运行流¶

右键点击“飞机”图标并选择 Enable all Controller Services。
右键点击导入的进程组并选择 Start。连接器开始数据引入。

如果您需要更改问题查询条件，或者想彻底重新启动引入，请执行以下步骤，以确保目标表中的数据一致：

右键点击 FetchJiraIssues 处理器并将其停止。
右键点击 FetchJiraIssues 处理器，然后选择 View State。
在 State 对话框中，选择 Clear State。此操作将清除处理器的状态，并允许它再次提取所有问题。
可选：如果要更改问题查询条件，请右键点击导入的进程组并选择 Parameters。按需更新参数。
可选：如果要更改目标表名称，请右键点击导入的进程组并选择 Parameters。更新 Destination Table 参数。
右键点击 FetchJiraIssues 处理器并选择 Start。连接器开始数据引入。
引入后，数据在 Snowflake 目标表中可用，在目标视图中以扁平化格式提供。该视图包含 Jira 实例中所有可用的字段。

访问数据¶

从 Jira 提取的数据在目标表中可用。针对 Jira 问题提取的所有字段均以从 API 提取的原始形式在 ISSUE 列中以对象形式提供。

为了帮助查询数据，基于目标表创建了扁平化视图。视图名称是表名和后缀 _VIEW 的组合。例如，如果目标表命名为 JIRA_ISSUES，则视图将命名为 JIRA_ISSUES_VIEW。在视图中，所有问题字段均会提取并作为单独的列提供。列名设置为字段标签。如果存在许多标签相同的问题，则会在列名中添加带字段 ID 的后缀以确保唯一性。例如，如果有两个 IDs 为 customfield_1、customfield_2 的字段，则这两个字段的标签都设置为 Custom Field，视图中的列将分别命名为 Custom Field (customfield_1)、Custom Field (customfield_2)。