共享已保存的对象

如果您的对象存储任何指向其他对象的链接（使用对象类型/ID），则需要采取特定步骤以确保这些链接在 8.0 升级后继续正常工作。

⚠️ 此步骤必须在 7.16 版本之前完成。 ⚠️

如果您对问题 1的回答为“是”，则需要确保您的对象链接仅存储在根级别的 references 字段中。当给定对象的 ID 更改时，此字段将相应地为其他对象更新。

下图显示了从“案例”对象到“操作”对象的对象链接的两个不同示例。顶部显示了链接到另一个对象的错误方式，底部显示了正确的方式。

如果您的对象没有使用根级别的 references 字段，则需要在8.0 版本之前添加迁移来修复该问题。这是上述示例的迁移函数：

function migrateCaseToV716(
  doc: SavedObjectUnsanitizedDoc<{ connector: { type: string; id: string } }>
): SavedObjectSanitizedDoc<unknown> {
  const {
    connector: { type: connectorType, id: connectorId, ...otherConnectorAttrs },
  } = doc.attributes;
  const { references = [] } = doc;
  return {
    ...doc,
    attributes: {
      ...doc.attributes,
      connector: otherConnectorAttrs,
    },
    references: [...references, { type: connectorType, id: connectorId, name: 'connector' }],
  };
}

...

// Use this migration function where the "case" object type is registered
migrations: {
  '7.16.0': migrateCaseToV716,
},

深层链接是指向显示特定对象的页面的 URL。最终用户可能会将这些 URL 添加到书签或使用它们安排报表，因此确保这些 URL 继续工作至关重要。下图显示了指向 Canvas 工作台对象的深层链接示例：

请注意，某些 URL 可能包含指向多个对象的深层链接，例如，仪表板和索引模式的过滤器。

⚠️ 此步骤最好在 7.16 版本中完成；它必须在 8.0 版本之前完成。⚠️

如果您对问题 2的回答为“是”，则需要确保在使用 SavedObjectsClient 使用其 ID 获取对象时，使用不同的 API 来执行此操作。现有的 get() 函数将仅使用其当前 ID 查找对象。为了确保您现有的深层链接 URL 不会中断，您应该使用新的 resolve() 函数；这将尝试使用其旧 ID和当前 ID 查找对象。

简而言之，如果您的深层链接页面之前有类似这样的内容：

const savedObject = savedObjectsClient.get(objType, objId);

则需要将其更改为以下内容：

const resolveResult = savedObjectsClient.resolve(objType, objId);
const savedObject = resolveResult.saved_object;

SavedObjectsResolveResponse 接口具有四个字段，汇总如下：

SavedObjectsClient 在服务器端和客户端都可用。您可以通过自定义 HTTP 路由在服务器端获取对象，也可以直接在客户端获取对象。无论哪种方式，都需要将 outcome 和 alias_target_id 字段传递给您的客户端代码，并且您应该在下一步中相应地更新您的 UI。

⚠️ 此步骤最好在 7.16 版本中完成；它必须在 8.0 版本之前完成。⚠️

空间插件 API 公开了您应该使用的 React 组件和函数，以便以一致的方式为最终用户呈现您的 UI。您的 UI 将需要使用 Core HTTP 服务和空间插件 API 来执行此操作。

您的页面应根据结果进行更改：

⚠️ 此步骤必须在 8.0 版本中完成（不早于也不晚于）。⚠️

在完成步骤 3之后，您可以添加代码来转换您的对象。

在注册您的对象时，您需要更改 namespaceType，并添加 convertToMultiNamespaceTypeVersion 字段。当用户安装 Kibana 8.0 版本时，此特殊字段将触发在核心迁移升级过程中发生的实际转换。

保存的对象可以选择使用加密保存的对象插件进行加密。很少有对象类型会被加密，因此大多数插件开发人员不会受到影响。

⚠️ 此步骤必须在 8.0 版本中完成（不早于也不晚于）。⚠️

如果您对问题 3的回答为“是”，则需要采取其他步骤以确保您的对象在转换过程后仍然可以解密。加密的保存对象使用某些字段作为“额外身份验证数据” (AAD) 的一部分，以防御不同类型的加密攻击。对象 ID 是此 AAD 的一部分，因此，在更改对象的 ID 后，该对象将无法使用标准流程进行解密。

为了缓解这个问题，您需要添加一个“无操作”的 ESO 迁移，该迁移将在 8.0 升级过程中对象转换后立即应用。这将使用其旧 ID 解密该对象，然后使用其新 ID 重新加密该对象。

在注册对象时，需要设置正确的 namespaceType。如果您有一个现有的“可共享”对象类型，您可以直接更改它。

如果一个对象被共享到多个空间，则必须使用 force 删除选项才能删除。您应该始终注意保存的对象是否存在于多个空间中，并且在这种情况下应警告用户。

如果您的 UI 允许用户删除您的对象，则可以定义如下警告消息

const { namespaces, id } = savedObject;
const warningMessage =
  namespaces.length > 1 || namespaces.includes('*') ? (
    <FormattedMessage
      id="myPlugin.deleteObjectWarning"
      defaultMessage="When you delete this object, you remove it from every space it is shared in. You can't undo this action."
    />
  ) : null;

堆栈管理中的数据视图页面使用类似的方法在其删除确认模态框中显示警告。

用户将需要一种方法来查看您的对象当前分配给哪些空间，并将它们共享到其他空间。您可以通过两种方式实现此目的，并且许多使用者希望同时实现这两种方式

我们实现了“可共享”对象类型，作为当前具有隔离对象但尚未准备好支持完全可共享对象的用户的中间步骤。这主要是因为我们要确保所有对象类型在 8.0 版本中同时转换，以最大程度地减少最终用户体验的混乱和中断。

我们意识到，对于某些 Kibana 团队来说，转换过程及其所需要的一切都可能是一项不小的工作，需要在 8.0 版本之前做好准备。只要对象是可共享的，就可以确保其 ID 是全局唯一的，因此在适当的时候稍后使该对象可共享将是微不足道的。

开发人员可以轻松地翻转开关，将可共享的对象变成可共享的对象，因为它们的序列化方式相同。但是，我们认为，每个使用者都需要制定自己的计划，并在使对象可共享时进行其他 UI 更改。例如，某些用户可能无权访问“保存的对象管理”页面，但我们仍然希望这些用户能够查看他们的对象存在于哪些空间中并将它们共享到其他空间。每个应用程序都应添加相应的 UI 控件来处理此问题。

这是因为隔离对象是如何序列化为原始 Elasticsearch 文档的。当今，每个原始文档 ID 都包含其空间 ID (命名空间) 作为前缀。当对象被复制或导入到其他空间时，它们会保留相同的对象 ID，只是在序列化为 Elasticsearch 时，它们具有不同的前缀。这导致了许多 Kibana 安装在不同空间中具有相同对象 ID 的保存对象的情况。

一旦对象被转换，我们需要删除此前缀。由于迁移过程的限制，我们无法主动检查这是否会导致冲突。因此，我们决定为非默认空间中的每个对象预先重新生成对象 ID，以确保每个对象 ID 成为全局唯一的。

如问题 2中所述，某些 URL 可能包含多个对象 ID，实际上是深度链接到多个对象。这些应根据具体情况由插件所有者自行决定处理。一个好的经验法则是

理想情况下，如果深层链接页面上的辅助对象解析为 'aliasMatch' 结果，则使用者应将用户重定向到具有新 ID 的 URL 并显示 Toast 消息。这样做的原因是，我们不希望用户过度依赖旧版 URL 别名。但是，对于 8.0 版本，不认为对辅助对象进行此类处理至关重要。

如上所述，当对象转换为可共享时，如果它存在于非默认空间中，则其 ID 将被更改。为了保留其旧 ID，我们还创建了一个名为旧版 URL 别名（简称“别名”）的特殊对象；此别名保留目标对象的旧 ID (sourceId)，并且包含指向目标对象新 ID (targetId) 的指针。

别名设计为对最终用户大多不可见。没有直接管理它们的 UI。我们的愿景是，别名将被用作帮助我们完成 8.0 升级过程的临时措施，但我们将引导用户远离对别名的依赖，以便我们最终可以弃用并删除它们。

resolve() 函数会检查具有给定 ID 的对象是否存在，以及是否有一个对象具有给定 ID 的别名。

结果 1

当您使用对象的当前 ID 解析对象时，结果为 'exactMatch'

这可能发生在默认空间和非默认空间中。

结果 2

当您使用对象的旧 ID（其别名的 ID）解析对象时，结果为 'aliasMatch'

此结果只能发生在非默认空间中。

结果 3

第三个结果是一个边缘情况，是其他结果的组合。如果您解析一个对象 ID 并找到两个对象 - 一个作为完全匹配项，另一个作为别名匹配项 - 则结果为 'conflict'

我们实际上有控制措施来防止在您共享、导入或复制对象时发生这种情况。但是，如果以某种方式创建对象或用户篡改对象的原始 ES 文档，则此情况仍然可能会发生在几种不同的情况下。由于我们无法 100% 排除这种情况，因此我们必须优雅地处理它，但我们预计这种情况很少发生。

重要的是要注意，当发生 'conflict' 时，返回的对象是“最正确”的匹配项 - ID 与其完全匹配的对象。

阅读本指南，您可能会认为在任何地方使用 resolve() 而不是 get() 更安全或更好。实际上，我们做出了明确的设计决策，添加了一个单独的 resolve() 函数，因为我们希望限制旧版 URL 别名的影响和依赖。为此，我们会根据 resolve() 的使用次数和遇到的不同结果收集匿名使用数据。如果 resolve() 的使用次数多于必要次数，则该使用数据将不太有用。

最终，resolve() 只应用于涉及用户控制的对象深层链接的数据流。没有理由更改任何其他数据流以使用 resolve()。

外部插件（那些未随 Kibana 提供的插件）可以使用本指南将任何隔离对象转换为可共享或完全可共享！如果您是外部插件开发人员，则步骤相同，但是您无需担心在特定版本之前完成任何操作。您唯一需要知道的是，您的插件在 8.0 版本之前无法转换您的对象。

有关用户应如何受到影响的更多详细信息，请参阅已保存对象 ID 文档。