UIP 是连接器构建器的初始值；连接器

用于框架、编辑、检查和验证本地 Integration Service 连接器的语法和选项 — 初始化构建器、初始化预设应用、初始化标头删除、检查和验证。

属于uip is connectors builder本地创作工具链的一部分。本页介绍拥有连接器磁盘Shell的两个动词：

• builder init — 创建新的连接器，或编辑从当前目录解析的连接器上的字段。还拥有 init preset apply（基本/分页配置捆绑包的种子）和 init header delete（删除全局请求标头）。
• builder inspect / builder validate — 只读结构摘要和 CI 可评分的通过/失败检查集。它们直接位于 builder 下，命令路径中没有 connector 包装器。

有关框架内活动、身份验证、触发器或低级别文件编辑的信息，请参阅同级页面。

概念

• 创建与编辑调度— init根据连接器是从--connector-dir （还是当前目录，仅扫描当前目录本身，而不是子目录，这与其他构建器命令的回退分辨率不同）解析来决定其模式。无法解析 →创建连接器（需要--name ，搭建新的树和默认种子）。一个“解决”→ “编辑” （只有您传递的标志会更改；磁盘上的其他所有内容保持原样）。如果需要匹配多个连接器目录，则 init 会失败，并显示 Code: "connectorAmbiguous"，而不是猜测 — 显式传递 --connector-dir。
• 为什么init不扫描子目录— 当当前目录中没有可解析的连接器时，所有其他构建器命令都会回退以扫描直接子目录（请参阅父页面上的概念）。init有意跳过该回退：扫描可能会解析 cwd 下的同级连接器目录，并对其进行静默编辑或重命名，而不是创建新目录。从连接器自己的目录中运行 init，或传递 --connector-dir 在其他位置编辑。
• init折叠在一起— 这单个命令替换了以前单独的connector scaffold 、 metadata set 、 global set和基本/分页config preset显示的内容，因此其他三个创作动词（ auth 、 activity 、 trigger ）保持缩小范围。此处未公开为标志的长尾element.json /元数据字段（ displayOrder 、 extended 、 typeOauth 、 cloneable 、 tags等）将改为遍历“触发器和状态”页面上的state patch 。
• 创建时的登录要求— 创建不带--organization连接器需要有效登录，因为元素密钥 ( design-{org}-{slug} ) 会覆盖组织。这将检查实际的登录状态，而不仅仅是组织名称是否在本地缓存——过期或刷新失败的会话会使检查失败，即使uip login status本身仍会报告成功。对于离线或 CI 构建，显式传递 --organization <slug>。
• 标头创建与删除不对称— 添加或更新全局标头合并到init --header VendorName=value （可重复）中。删除一个即为单独的 init header delete <vendor-name> — state patch 无法执行单个标头操作，因为它无法直接处理单个 element.json parameters[] 数组项目。

大纲

uip is connectors builder init [--name <name>] [--connector-dir <path>] [options...]
uip is connectors builder init preset apply --kind <base|pagination> [--override <key=value>]... [--connector-dir <path>] [--force]
uip is connectors builder init header delete <vendor-name> [--connector-dir <path>]
uip is connectors builder inspect [--connector-dir <path>]
uip is connectors builder validate [--connector-dir <path>]

uip 是连接器构建器初始化

在磁盘上创建或配置连接器的 Shell。

备注：

使用此选项来引导全新的连接器 (--name)，或为已存在的连接器设置连接器级字段（名称、说明、类别、基本 URL、标头、生命周期、层级）。要添加资源/活动，请使用“活动和挂钩”页面上的activity create 。要配置内联--auth代码之外的身份验证，请在“身份验证”页面上使用auth set 。要编辑此命令不会公开为标志的长尾 element.json 字段，请使用 state patch。

选项

长	值	描述
--name <name>	字符串	显示名称，例如'Acme Widgets'。创建时为必填项；元素密钥和默认文件夹从中派生。
--connector-dir <path>	路径	连接器目录。有关特定于init的解析行为，请参阅上述概念。
--organization <name>	Slug	元素密钥 (design-{org}-{name}) 的组织缩略名。仅创建模式；默认为您登录的组织。
--description <text>	字符串	单行连接器说明。
--categories <csv>	csv	以逗号分隔的类别列表。匹配不区分大小写；批准的值将标准化为其批准的拼写（例如crm → CRM）。无法识别的类别会在此处快速失败，而不是稍后在 validate 失败。
--activity-color <hex>	HEX	Studio 活动用户界面的十六进制颜色。
--base-url <url>	url	默认基本 URL — 设置 base.url 配置条目。模板化 URL (https://{environment}/api) 会自动为其所需的后台插值配置条目设定种子。
--accept-type <value>	字符串	Accept 标头值。
--content-type <value>	字符串	Content-Type 标头值。
--header <kv>	VendorName=value	全局请求标头。可重复。
--lifecycle-stage <stage>	字符串	生命周期阶段，例如GA，BETA。
--tier <tier>	字符串	连接器层。
--auth <type>	字符串	内联配置身份验证（仅适用于创建模式）：任何 auth set --auth-type 值（oauth2、customApiKey、none、jwtOauth、firstPartyService 等）。若使用 oauth2，--authorization-url、--token-url 和 --scope 为必填项。除了以下标志之外，特定于类型的标志还需要 auth set。
--authorization-url <url>	url	OAuth2 登录/同意 URL。需要使用 --auth oauth2。
--token-url <url>	url	OAuth2 令牌端点。需要使用 --auth oauth2。
--token-refresh-url <url>	url	OAuth2 刷新端点。默认为 --token-url。
--token-revoke-url <url>	url	OAuth2 令牌撤销端点。
--scope <scope>	字符串	OAuth2 以空格分隔的作用域字符串。需要使用 --auth oauth2。
--api-key-param-name <name>	字符串	customApiKey — 供应商标头或查询参数名称。
--api-key-location <where>	header | query	customApiKey — 密钥发送位置。默认 header。
--api-key-prefix <prefix>	字符串	customApiKey — 文字前缀。
--key-config-name <key>	字符串	customApiKey — 内部配置密钥。默认 custom.api.key。
--key-config-display-name <name>	字符串	customApiKey — 用户界面标签。默认 API Key。
--force	标记	对现有条目应用差异，而不是出错。

示例

# Create a new connector (auth configured later)
uip is connectors builder init --name 'Acme Widgets'

# Create + OAuth2 + base URL in one call
uip is connectors builder init --name 'Acme Widgets' --base-url https://api.acme.com \
  --auth oauth2 --authorization-url https://acme.com/oauth/authorize \
  --token-url https://acme.com/oauth/token --scope 'read write'

# Edit an existing connector — only the passed flags change
uip is connectors builder init --description 'Acme Widgets connector' --categories crm,sales

数据形状（--输出 json）

{
  "Code": "ConnectorInitialized",
  "Data": {
    "Mode": "created",
    "ElementKey": "design-myorg-acmewidgets",
    "RepoName": "acme-widgets",
    "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets",
    "FilesCreated": ["app/element/element.json", "..."],
    "OrganizationName": "myorg",
    "OrganizationNameSource": "login",
    "HeadersSeeded": [],
    "BaseUrlSet": false,
    "MetadataChanges": [],
    "AuthConfigured": null
  }
}

Mode 为 "created" 或 "edited"。编辑模式会返回较窄的 Data 形状：Mode、ConnectorRoot、HeadersChanged、MetadataChanges、BaseUrlSet — 没有 FilesCreated、OrganizationName 或 AuthConfigured，因为这些用法仅适用于新的框架。

UIP 是连接器构建器初始预设应用

应用规范的配置条目捆绑包：base（基本 URL 加上选择/空/实例键）或 pagination（四个分页键）。

备注：

使用此选项，可在一次调用中为基本或分页配置键设定种子。事件/轮询捆绑包是通过 trigger create --event-kind 到达的单独预设，而非通过此命令到达。要添加一个定制的配置条目而不是捆绑包，请使用 state patch element.json/configuration/<key>。

选项

长	值	描述
--kind <kind>	base | pagination	必需。要应用的预设。
--override <kv>	key=value	每个条目的 defaultValue 覆盖。可重复。
--connector-dir <path>	路径	连接器目录。
--force	标记	对现有条目应用差异，而不是出错。

示例

uip is connectors builder init preset apply --kind pagination

数据形状（--输出 json）

{
  "Code": "ConfigPresetApplied",
  "Data": {
    "Kind": "pagination",
    "Added": ["pagination.max"],
    "Updated": [],
    "Unchanged": [],
    "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets"
  }
}

UIP 是连接器构建器初始标头删除

按供应商名称删除全局请求标头。

备注：

使用此选项可删除不再发送的全局标头。要添加或更新，请使用 init --header VendorName=value — 没有 init header create；该操作依赖于 init 本身。

参数

名称	必填	用途
<vendor-name>	是	要删除的供应商标头名称。

选项

长	值	描述
--connector-dir <path>	路径	连接器目录。

示例

uip is connectors builder init header delete X-Tenant

数据形状（--输出 json）

{
  "Code": "GlobalHeaderRemoved",
  "Data": { "ConnectorRoot": "/work/periodic-design-myorg-acmewidgets", "VendorName": "X-Tenant" }
}

uip 是连接器构建器检查

生成连接器的只读结构化概述：身份验证类型、配置、资源（包含标准资源文件和挂钩）、全局挂钩、事件和元数据。

备注：

使用此选项在编辑现有连接器之前快速获取其概览，或确认存在哪些资源、挂钩和身份验证类型。对于通过/失败检查，请使用 validate，代替结构摘要。

选项

长	值	描述
--connector-dir <path>	路径	连接器目录。

示例

uip is connectors builder inspect --connector-dir ./my-acme-connector

数据形状（--输出 json）

{
  "Code": "ConnectorInspected",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "ElementKey": "design-myorg-acmewidgets",
    "Name": "Acme Widgets",
    "Description": "Acme Widgets connector",
    "AuthTypes": ["oauth2"],
    "ConfigCount": 5,
    "ConfigKeys": ["base.url", "..."],
    "ResourceCount": 12,
    "ResourceSummary": {
      "/auth_validation": { "Methods": ["GET"], "Type": "standard", "StandardResourceFile": "auth_validation.json", "Hooks": [] }
    },
    "GlobalHooks": [],
    "HasEvents": false,
    "EventTypes": [],
    "Categories": ["CRM"],
    "LifecycleStage": "GA",
    "Metadata": { "...": "verbatim element-metadata.json content" }
  }
}

ResourceSummary 由资源的实际磁盘路径作为密钥（例如/auth_validation），Metadata 是 element-metadata.json 的原义内容。两者都不受 CLI 通常的帕斯卡拼写法密钥规范化的约束——原始密钥与其在磁盘上的显示完全相同，因此从此输出构建的选取器（例如/auth_validation 和 {sys_id}）将与真实文件路径匹配，而不是损坏的 /authValidation/{sysId} 变体。

uip 为连接器构建器构建器提供验证

对连接器运行完整检查集，并发出结构化报告。当连接器无效时，以非零值退出，以便 CI 可以对其进行门控。

备注：

使用此功能在导入或发布之前对 CI 中的连接器进行门控，并在 element.json、标准资源文件、挂钩和元数据中查找错误、警告和建议。要浏览连接器的结构而不是运行检查，请使用 inspect。

选项

长	值	描述
--connector-dir <path>	路径	连接器目录。

示例

uip is connectors builder validate

uip is connectors builder validate --connector-dir ./my-acme-connector

数据形状（--输出 json）

{
  "Code": "ConnectorValidation",
  "Data": {
    "ConnectorRoot": "/work/my-acme-connector",
    "ElementKey": "design-myorg-acmewidgets",
    "Valid": true,
    "Errors": [],
    "Warnings": [],
    "Info": ["Configuration entries: 5"],
    "Summary": "PASS: 0 error(s), 0 warning(s)"
  }
}

在通过和失败情况下都会发出该报告 — 失败报告仍返回 Result: "Success"，Valid: false 为 Data（命令本身没有错误），但流程将以非零退出代码退出，以便 CI在不解析正文的情况下对结果进行设置。

相关内容

• uip 是连接器构建器— 概念和租户生命周期动词（ download 、 import 、 publish 、 publish-status ）。
• 身份验证— 配置连接器的身份验证方案。
• 活动和挂钩— 定义连接器的活动执行的操作。
• 触发器和状态— 事件触发器和低级别元素文件编辑。

另请参阅

• Integration Service 工具概述
• 全局选项
• 退出代码