Windchill+ 管理帮助 > Windchill+ 实施管理 > 自定义 > 自定义模式 > 与外部系统集成 > 支持对公开端点进行出站 HTTPS 调用 > 与 PTC 共享部署特定的外部连接信息
与 PTC 共享部署特定的外部连接信息
使用 captureExternalConnections 实用程序，可以与 PTC 共享部署特定的外部连接信息。这样，多个 Windchill+ 部署就可以连接到外部系统的不同 URL。所有部署特定的外部 URL 和机密在运行时均可用，并且可以专门为每个 Windchill+ 部署 (例如开发、测试和生产) 进行填充。
Windchill+ 安装中包含此实用程序。可以在 Linux 系统上从现有 Windchill+ 安装复制该实用程序，并可独立于 Windchill+ 将该实用程序应用于任何其他 Linux 系统。在 Windows 系统上，此实用程序能够与诸如 MSYS2 和 Cygwin 之类的 Linux 应用程序集一起运行。在 PTC cloud portal 上请求 Windchill 模板的新实例时，默认情况下，该实例包括 MSYS2。
像一些其他 Windchill+ 实用程序一样，captureExternalConnections 是一个 shell 脚本，需要使用 JSON 文件中提供的机密以及文件系统中提供的证书。有关详情，请参阅下面的“运行实用程序的步骤”部分。该实用程序使用 PTC 提供的公钥来加密信息，并将 YAML 包上传到特定部署 (开发或生产) Azure 容器。
通过克隆 Windchill+ 生产部署来创建开发或测试环境时，生产中指定的外部端点 URL 可能会在开发或测试环境中运行，而导致数据损坏。为防止此类跨环境连接，与 PTC 共享部署特定的外部连接信息，这一点非常重要。
之后，使用 CustomIntegrationHelper API 创建的 Windchill+ 自定义会使用此外部连接信息与提供的端点进行通信。为每个 Windchill+ 部署提交单独的连接信息时，可将相同的自定义代码用于不同的 Windchill+ 部署。可以使用 Code and Configuration (CCD) 实用程序来提交自定义。有关 CustomIntegrationHelper 中所提供 API 的详情，请参阅适用的 Windchill Javadoc。
通过 CCD 实用程序提交的自定义代码可用于实现不同的 Windchill+ 部署，而通过 captureExternalConnections 实用程序共享的外部连接信息 (json 参数) 特定于各个 Windchill+ 部署。
要运行此实用程序，请确保您掌握以下信息：
• 对 captureExternalConnections 实用程序的访问。
• PTC 通过电子邮件提供的 BLOB_SAS_URL。
• PTC 通过电子邮件提供的用于加密机密的公钥。
• client-keycertchain - 只有在端点需要客户端证书时，才需要客户端密钥链。
• server-certchain - 只有在端点为非公共端点时，才需要服务器证书链。
* 
请求 Windchill+ 部署时，会以电子邮件附件形式从 PTC 接收 (其中包含加密连接信息的) Blob 的 Blob SAS URL，以及用于加密连接信息的 Public Key。您可能会收到其他电子邮件，其中包含 Blob SAS URL，但在捕获外部连接实用程序中，您必须输入随公钥一起接收的 Blob SAS URL。
* 
• 请确保 (PEM 编码) 证书正确且是从有效源获得的。只有在建立外部连接时要求客户端证书的情况下，才需要提供客户端证书。只有在建立外部连接时所用证书是由鲜为人知的证书颁发机构颁发的情况下，才需要提供服务器证书，该证书预设不受 Java 运行时信任。
• 可以通过多种方式实现身份验证。某些外部连接可能需要静态令牌，而其他外部连接可能需要其他实体颁发的令牌。即使在令牌颁发机构之间，也可能存在差异。最好使用此实用程序来仅捕获静态机密 (如租户 ID、客户端 ID、客户端机密和令牌颁发机构 URL)，并实施相应的流程来获取外部连接所需的短期令牌。
运行此实用程序的步骤
1. 通过运行以下命令，生成 JSON 模板文件：
${WT_HOME}/prog_examples/IntegrationsExample/captureExternalConnections.sh -t <template-file-path>
在 <template-file-path> 中，指定 JSON 文件的路径。
2. 根据模板文件中提及的说明和约束，创建 JSON 文件。JSON 文件应包含有关部署特定的端点的连接信息。有关详情，请参阅下面的要在 JSON 文件中提供的信息部分。
3. 在同一终端中，通过执行以下命令，在本地捕获机密：
${WT_HOME}/prog_examples/IntegrationsExample/captureExternalConnections.sh -f <json-file-path>
在 <json-file-path> 中，指定其中包含外部连接信息的 JSON 文件的路径。
成功执行脚本后，系统随即显示以下消息："Connection information submitted successfully."
* 
• 即使是在本地捕获连接信息，也必须提供 BLOB_SAS_URL 和公钥进行加密。
• 要捕获外部端点，可以选择使用 JSON 文件中的 apply_at 参数。如果跳过此参数，则不会向 PTC 回滚连接信息。不过，可通过配置本地 Windchill 部署来使用所提供的连接信息。
JSON 模板文件
{
"blob_sas_url": "http://samplestorageaccount.blob.core.windows.net/connection-yaml-tests/connectionInfo.yaml",
"external_connections": {
"sample_connection.alpha": {
"baseurl": "https://acme.com"
},
"sample_connection.bravo": {
"baseurl": "https://bravo.com",
"secrets": {
"client_cert": "/path/to/client.keycertchain",
"secret.username": "alpha27",
"secret.age": "24"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "/path/to/asymmetric_encryption_public_key_<***>.txt"",
"apply_at": "2024-03-30T12:24"
}
可以提交其中包含外部端点名称 endpoint1 和 endpoint2 的自定义代码。通过使用 captureExternalConnections 实用程序指定不同的连接信息，可以将此自定义代码同时用于 Windchill+ 开发部署和生产部署。请参阅以下部署特定的 JSON 文件。
Windchill+ 开发部署的参数文件：devConnections.json
Windchill+ 生产部署的参数文件：prodConnections.json
{
"blob_sas_url": "...deployment specific URL as received from PTC...",
"external_connections": {
"endpoint1": {
"baseurl": https://foo-dev.acme.com
},
"endpoint2": {
"baseurl": https://bar-dev.acme.com,
"secrets": {
"client_cert": "/path/to/client-dev.keycertchain",
"secret.username": "user1",
"secret.age": "5"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "/path/to/asymmetric_encryption_public_key_<dev***>.txt",
"apply_at": "2024-03-30T12:24+5:30"
}
{
"blob_sas_url": "...deployment specific URL as received from PTC...",
"external_connections": {
"endpoint1": {
"baseurl": https://foo-prod.acme.com
},
"endpoint2": {
"baseurl": https://bar-prod.acme.com,
"secrets": {
"client_cert": "/path/to/client-prod.keycertchain",
"secret.username": "user2",
"secret.age": "4"
}
},
"url_fragments": {
"get_user_name": "users/username",
"get_user_age": "users/age"
}
},
"public_key_for_encrypting_custom_secrets": "/path/to/asymmetric_encryption_public_key_<Prod***>.txt",
"apply_at": "2024-03-30T17:56+5:30"
}
有关如何通过 CustomIntegrationHelper 使用连接信息以及自定义示例的信息，请参阅集成示例。
要在 JSON 文件中提供的信息
参数
必需或可选
说明
blob_sas_url
强制
此参数用于指定 PTC 通过电子邮件提供的 Blob SAS URL。此参数应指向 connectionInfo.yaml。例如：
https://somestorageaccount.blob.core.windows.net/somecontainer/connectionInfo.yaml?sp=rw&st=2024-03-11T11:05:43Z&se=2024-03-12T19:05:43Z&spr=https&sv=2022-11-02&sr=b&sig=XHIXmZAL5b4wBxWg17AqS27Yvn8pa%2B8ZNPafxNoU0pE%3D
connection.name
强制
此参数用于指定唯一的连接名称。可以根据需要，添加一个或多个连接。
例如：
sample.connection.alpha
sample.connection.bravo
erp.dev
baseurl
强制
此参数用于为各个连接指定基本 URL。基本 URL 名称仅允许使用下列字符：a-z 0-9。_
例如：
client_cert
可选
此参数用于指定客户端证书或链的路径，以及无密码的密钥。例如：/path/to/client.keycertchain
secret.name
可选
此参数用于指定 API 令牌和登录凭据等任何其他机密。机密名称仅允许使用下列字符：a-z 0-9。_
例如：
k>#=B3*jKX!Fa)e(;TsygY6P72Rd%:Ar
x-acme-header=AcmeMaterial
server_cert
可选
如果服务器 SSL 证书由鲜为人知的认证机构颁发，请指定服务器证书或链的路径。
例如：/path/to/server.certchain
url_fragments
可选
如果多个端点共享相同的标识、服务器或客户端机密，则可以指定与同一基本 URL 关联的 URL 片段。
片段名称仅允许使用以下字符：a-z 0-9。_
例如：/inventory/api
public_key_for_encrypting_custom_secrets
强制
此参数用于指定加密公钥的路径。公钥文件由 PTC 通过电子邮件提供。
例如：/path/to/asymmetric_encryption_public_key_<***>.txt
apply_at
可选
此参数用于提供 ISO 8601 时间戳，以表示开始回滚连接信息的时间。时间戳必须至少比当前时间晚一小时。如果跳过 apply_at 参数，则不会回滚连接信息。不过，可通过配置本地 Windchill 部署来使用所提供的连接信息。
例如：2024-03-11T11:24+00:00
* 
如果在 1 小时内为同一连接提供了另一组连接详情，则新信息将应用于两次运行。
* 
尽管向 PTC 提交新机密与使用这些机密这两项操作之间最少延迟一小时，也可以选择提前安排新机密值的回滚。但是，在新机密值的回滚排程开始之前，Windchill+ 自定义代码将继续使用旧机密值。如果希望外部端点集成在此时间范围内运行，则必须相应地修改 CCD 中的自定义代码。或者，可能会以重叠的时间表，回滚新机密值和逐步淘汰的旧机密值。
* 
上传连接详情或进行配置变更时，请遵循本部分中所述的步骤。重新运行 captureExternalConnections 实用程序以更新连接信息 (JSON 文件)，并允许已安排的业务流程应用这些配置，包括必要的重新启动。
这对您有帮助吗?