开放翻译环境（OTE）API核心

访问数据资源、映射数据模型、描述数据到本体并执行数据转换的框架

我们强烈建议您阅读官方文档中的此页面。

重要：从 v0.6.0 版本开始，OTEAPI Core 不再兼容 pydantic v1，但仅兼容 pydantic v2。有关将您的插件仓库迁移到 pydantic v2 的更多信息，请参阅 pydantic 文档的迁移指南。
截至 2023 年底，pydantic v1 仍将获得安全更新，但不会添加新功能。要继续使用 pydantic v1，应使用 OTEAPI Core 的 v0.5.x 版本。

关于 OTEAPI Core

OTEAPI Core 提供了 OTEAPI 的核心功能，代表 开放翻译环境 API。

它使用 策略 软件设计模式来实现对大量数据资源的简单且易于扩展的访问。通过将描述数据的模型映射到本体，支持语义互操作性。提供了一套策略接口，可以作为策略实现的抽象类，以及它们配置中使用的数据模型。此仓库还包含了一些标准策略的实现，例如文件下载、解析 Excel 文档。还支持转换，主要用于在表示之间转换数据，但转换也可以用于在简单的工作流程中运行模拟。

OTEAPI Core 包括

• 一组标准策略；
• 一个用于加载标准策略以及第三方策略的插件系统；
• 用于配置策略的数据模型；
• 一个 Python 库，通过它可以访问数据；以及
• 一个高效的数据缓存模块，可以避免多次下载相同的内容。

策略类型

下载策略

下载策略模式使用给定的协议将内容下载到数据缓存中。它们使用 ResourceConfig 数据模型进行配置，使用 downloadUrl 字段的方案进行策略选择。可以使用 configuration 字段通过 DownloadConfig 数据模型来配置如何将下载的内容存储在缓存中。

标准下载策略：file、https、http、sftp、ftp

解析策略

解析策略模式将内容从数据缓存转换为 Python 字典。与下载策略一样，它们使用 ResourceConfig 数据模型进行配置，使用 mediaType 字段进行策略选择。可以通过 configuration 字段提供额外的特定策略配置。

标准解析策略：application/json、image/jpg、image/jpeg、image/jp2、image/png、image/gif、image/tiff、image/eps、application/vnd.openxmlformats-officedocument.spreadsheetml.sheet、application/vnd.sqlite3

资源策略

资源策略模式可以检索/上传数据到外部数据服务。它们使用 ResourceConfig 数据模型进行配置，使用 accessUrl 和 accessService 字段的方案。使用 accessUrl 的方案进行策略选择。

映射策略

将数据模型中的字段/属性映射到本体概念的策略。

过滤器策略

过滤器策略可以更新其他策略的配置。它们还可以更新数据缓存中的值。

标准过滤器策略：filter/crop、filter/sql

函数策略

函数策略是同步转换，通常在托管 OTE 服务的服务器上直接运行。

转换策略

转换策略是函数策略的一种特殊形式，旨在用于长期运行的转换。在这方面，它们代表在后台或外部资源上运行的异步函数。

标准转换策略：celery/remote

转换策略已经通过 get() 方法将转换的执行与统一策略接口结合起来。 get() 的目的是启动一个异步过程并返回一个 task_id，该 ID 可以通过 status() 方法（在管道之外）进行查询。

插件入口点

策略的注册和查找是通过 入口点 来实现的。

特殊的组名允许理解策略类型，而入口点值允许理解特定类实现了哪种类型的策略。可以在 入口点策略表 中查看可识别的入口点组名的完整概述。

定义入口点

在以下示例中，让我们假设我们有一个可以通过 my_plugin 在 Python 中导入的包，其中包含两个下载策略和一个解析策略

1. 一个点对点下载策略，在名为 Peer2PeerDownload 的类中实现，可从 my_plugin.strategies.download.peer_2_peer 中导入。
2. 一个 MongoDB 下载策略，在名为 MongoRetrieve 的类中实现，可从 my_plugin.strategies.mongo 中导入。
3. 一个 MongoDB 解析策略，在名为 MongoParse 的类中实现，可从 my_plugin.strategies.mongo 中导入。

现在有几种不同的方法可以通过入口点让 Python 环境了解这些策略。

setup.py

在包的 setup.py 文件中，可以指定入口点。这里，展示了使用 setuptools 的示例片段

# setup.py
from setuptools import setup

setup(
    # ...,
    entry_points={
        "oteapi.download": [
            "my_plugin.p2p = my_plugin.strategies.download.peer_2_peer:Peer2PeerDownload",
            "my_plugin.mongo = my_plugin.strategies.mongo:MongoRetrieve",
        ],
        "oteapi.parse": [
            "my_plugin.application/vnd.mongo+json = my_plugin.strategies.mongo:MongoParse",
        ]
    },
)

YAML/JSON 自定义文件

使用自定义文件，这些文件随后将被解析并用于 setup.py 文件中。

entry_points:
  oteapi.download:
  - "my_plugin.p2p = my_plugin.strategies.download.peer_2_peer:Peer2PeerDownload"
  - "my_plugin.mongo = my_plugin.strategies.mongo:MongoRetrieve"
  oteapi.parse:
  - "my_plugin.application/vnd.mongo+json = my_plugin.strategies.mongo:MongoParse"

{
  "entry_points": {
    "oteapi.download": [
      "my_plugin.p2p = my_plugin.strategies.download.peer_2_peer:Peer2PeerDownload",
      "my_plugin.mongo = my_plugin.strategies.mongo:MongoRetrieve"
    ],
    "oteapi.parse": [
      "my_plugin.application/vnd.mongo+json = my_plugin.strategies.mongo:MongoParse"
    ]
  }
}

setup.cfg/pyproject.toml

更现代的方法是使用 setup.cfg 或 pyproject.toml。

[options.entry_points]
oteapi.download =
    my_plugin.p2p = my_plugin.strategies.download.peer_2_peer:Peer2PeerDownload
    my_plugin.mongo = my_plugin.strategies.mongo:MongoRetrieve
oteapi.parse =
    my_plugin.application/vnd.mongo+json = my_plugin.strategies.mongo:MongoParse

语法和语义

如上所示，有几种不同的语法风格来列出入口点。然而，“值”在整篇文档中保持一致。

通用 Python 入口点

入口点的通用语法基于 ini 文件，并使用内置的 configparser 模块进行解析，该模块的描述见 此处。具体到入口点，其命名规则如下

[options.entry_points]
GROUP =
    NAME = VALUE

然后 VALUE 进一步拆分为：PACKAGE.MODULE:OBJECT.ATTRIBUTE [EXTRA1, EXTRA2]。

OTEAPI 策略入口点

从上述通用语法中，OTEAPI 核心然后实现关于策略语法的规则和需求。

1. 必须指定一个 CLASS（作为 OBJECT）。
2. NAME 必须恰好由两部分组成：PACKAGE 和策略类型值，形式为 PACKAGE.STRATEGY_TYPE_VALUE。
3. GROUP 必须是有效的 OTEAPI 入口点组，有关有效 OTEAPI 入口点组值的完整列表，请参阅 入口点策略表。

要了解策略类型值应该是多少，请参阅 入口点策略表。

入口点策略表

其他 OTEAPI 相关存储库

• OTEAPI 服务 - OTEAPI 核心的 RESTful 接口
• OTELib - OTEAPI 服务的 Python 接口
• OTEAPI 插件模板 - OTEAPI 插件的 cookiecutter 模板

安装

OTEAPI 核心可以通过以下方式安装

pip install oteapi-core

对于开发者

如果您想安装 OTEAPI Core 以获得开发环境，请从 GitHub 克隆仓库并安装。

git clone https://github.com/EMMC-ASBL/oteapi-core /path/to/oteapi-core
pip install -U --upgrade-strategy=eager -e /path/to/oteapi-core[dev]

注意，/path/to/oteapi-core 可以省略在第一行，但必须在第二行中更新，要么是 ./oteapi-core/oteapi-core，要么是 . 如果您使用 cd 命令进入已克隆仓库的生成文件夹。

可以省略 --upgrade-strategy=eager 部分。我们建议在专用虚拟环境中进行安装。

要测试安装，可以运行

cd /path/to/oteapi-core
pytest

如果在这个阶段遇到问题，请 提交一个问题。

使用 Docker 和 PostgreSQL

Docker 是创建可移植、隔离的应用程序环境的有效工具。以下是一个使用 Docker 设置 PostgreSQL 实例的示例

1. 创建 Docker 卷：Docker 卷允许数据在使用 Docker 容器时持久化。在此上下文中，我们创建一个名为 pgdata 的卷来存储数据库数据。

   docker volume create pgdata
   

2. 启动 Docker 容器：使用 docker run 命令通过 postgres 镜像启动一个新的 Docker 容器。以下是命令中使用到的选项的分解

   -d：在后台（分离模式）运行容器，释放您的终端。

   --name postgres：将容器命名为 postgres，允许在未来的 Docker 命令中引用。

   -e POSTGRES_PASSWORD=postgres：在容器中设置一个环境变量，将 PostgreSQL 数据库密码指定为 postgres。

   -p 5432:5432：将容器的 5432 端口映射到宿主机的 5432 端口，允许宿主机上的应用程序连接到容器中的 PostgreSQL 数据库。

   -v pgdata:/var/lib/postgresql/data：将 pgdata 卷挂载到容器中的 /var/lib/postgresql/data 路径，这是 PostgreSQL 数据文件的存储位置。

   --restart always：确保容器在停止时重新启动，除非手动停止，在这种情况下，只有在 Docker 守护进程启动时才会重新启动，通常在系统启动时。

   docker run  -d --name postgres \
       -e POSTGRES_PASSWORD=postgres \
       -p 5432:5432 \
       -v pgdata:/var/lib/postgresql/data \
       --restart always postgres
   

许可

OTEAPI Core 在 MIT 许可证下发布，版权所有 © SINTEF。

致谢

OTEAPI Core 由以下项目支持

• OntoTrans（2020-2024），该项目获得欧盟地平线 2020 研究和创新计划的资金，项目编号为 862136。

• VIPCOAT（2021-2025）获得欧盟地平线 2020 研究和创新计划的资金 - DT-NMBP-11-2020 材料建模开放创新平台，项目编号为 952903。

• OpenModel（2021-2025）获得欧盟地平线 2020 研究和创新计划的资金 - DT-NMBP-11-2020 材料建模开放创新平台，项目编号为 953167。