共享已保存的对象

如果您的对象存储了指向其他对象的*任何*链接（带有对象类型/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 版本之前完成。 ⚠️

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

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

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

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

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

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

⚠️ 此步骤必须在 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文档。