edfialliance/ods-api-publisher

Ed-Fi API Publisher

https://api.securityscorecards.dev/projects/github.com/Ed-Fi-Alliance-OSS/Ed-Fi-API-Publisher/badge](https://securityscorecards.dev/viewer/?uri=github.com/Ed-Fi-Alliance-OSS/Ed-Fi-API-Publisher)

概述

Ed-Fi API Publisher是一款实用工具，用于在同一版本的Ed-Fi ODS API实例之间移动数据和变更。它作为标准API客户端对两个API端点（源和目标）进行操作，因此不需要特殊的网络配置、直接的ODS数据库访问或特定的数据库引擎。从数据安全/隐私角度来看，它还需遵守与其通信的Ed-Fi ODS API端点执行的所有授权机制。

核心功能和特性

• 跨实例数据同步：在同一版本的Ed-Fi ODS API实例间移动数据和变更
• 灵活部署模型：支持三种部署模型
  • Pull模型：部署在目标（中央）API旁，从多个源API收集数据
  • Push模型：部署在源API旁，将数据推送到中央目标
  • Publishing模型：部署在源API旁，将数据推送到多个目标（如州教育机构和协作组织）
• 增量同步能力：若源API支持"Change Queries"功能，首次运行时执行全量数据发布，后续运行仅发布变更数据
• 状态跟踪：自动为每个源/目标组合在配置存储中维护已发布到特定目标的变更版本
• 安全合规：遵循Ed-Fi ODS API端点的所有授权机制

使用场景和适用范围

• 教育机构间的数据共享与同步
• 多区域教育数据中心的数据聚合
• 从多个学校或学区收集数据到中央教育机构
• 向多个监管机构或合作伙伴推送标准化教育数据
• 教育数据备份与灾备恢复

使用方法和配置说明

环境要求

• 源和目标Ed-Fi ODS/API必须为相同版本
• 目标ODS需配置具有适当发布权限的API客户端
• 运行环境需安装.NET 8.0

配置本地沙箱环境

在目标ODS上使用API Publisher前，必须创建并配置具有适当发布权限的API客户端。

对于Ed-Fi ODS / API 5.1至5.3版本：通过运行以下数据库脚本创建并分配API Publisher的声明集：

• Create-API-Publisher-Writer-Security-Metadata.sql
• Configure-Minimal-Sandbox-Client-as-API-Publisher-Writer.sql

使用API Publisher的三种方式

方式1 - 从二进制文件

1. 下载最新发布的API Publisher包：Ed-Fi API Publisher v1.3.0，访问页面并点击下载。
2. 将下载的NuGet包重命名为.zip扩展名：EdFi.ApiPublisher.1.3.0.nupkg → EdFi.ApiPublisher.1.3.0.zip。
3. 二进制文件位于EdFi.ApiPublisher.Win64文件夹中，文件名为EdFiApiPublisher.exe。

方式2 - 从Docker镜像

Ed-Fi API Publisher的Docker镜像可在Docker Hub获取：https://hub.docker.com/r/edfialliance/ods-api-publisher/tags%E3%80%82%E5%8F%AF%E5%B0%86%E5%85%B6%E5%8C%85%E5%90%AB%E5%9C%A8Docker%E7%8E%AF%E5%A2%83%E4%B8%AD%EF%BC%8C%E4%B8%8EEd-Fi%E5%A0%86%E6%A0%88%E7%9A%84%E5%85%B6%E4%BB%96%E7%BB%84%E4%BB%B6%E4%B8%80%E8%B5%B7%E4%BD%BF%E7%94%A8%E3%80%82

Docker运行示例：

bash
docker run -it edfialliance/ods-api-publisher:v1.3.0 \
  --sourceUrl=https://api.ed-fi.org/v5.2/api/ \
  --sourceKey=RvcohKz9zHI4 \
  --sourceSecret=E1iEFusaNf81xzCxwHfbolkC \
  --targetUrl=http://localhost:54746/ \
  --targetKey=minimal_sandbox_API_key \
  --targetSecret=minimal_sandbox_API_secret \
  --ignoreIsolation=true \
  --maxDegreeOfParallelismForPostResourceItem=5 \
  --maxDegreeOfParallelismForStreamResourcePages=3 \
  --includeDescriptors=true \
  --exclude=surveys

方式3 - 从源代码构建

若要从源代码构建API Publisher，在存储库根目录运行以下命令构建解决方案：

bash
dotnet build

API Publisher可执行文件（EdFiApiPublisher.exe）将位于.\EdFi.Tools.ApiPublisher.Cli\bin\Debug\net8.0子文件夹中。

发布数据到本地沙箱

重要提示： 修改API的安全元数据后，如果本地沙箱Ed-Fi ODS API已在运行，必须重启该服务。

首先，找到最小模板沙箱的API客户端的key/secret。可使用Sandbox Admin工具，或对EdFi_Admin数据库运行以下查询：

sql
SELECT  [Key], [Secret]
FROM    EdFi_Admin.dbo.ApiClients
WHERE   Name = 'Minimal Demonstration Sandbox'

以下表格显示用于发布的命令行参数：

注意：由于快速启动配置的特性（假设SQL Server和Ed-Fi-ODS API在本地开发机器上运行），我们将POST请求的并行度限制为5。具有专用API和数据库资源的架构应能支持更高的数值。

在包含所有二进制文件的文件夹中运行Ed-Fi API Publisher，执行以下命令，替换为自己的API客户端key和secret：

bash
.\EdFiApiPublisher.exe --sourceUrl=https://api.ed-fi.org/v5.2/api/ --sourceKey=RvcohKz9zHI4 --sourceSecret=E1iEFusaNf81xzCxwHfbolkC --targetUrl=http://localhost:54746/ --targetKey=minimal_sandbox_API_key --targetSecret=minimal_sandbox_API_secret --ignoreIsolation=true --maxDegreeOfParallelismForPostResourceItem=5 --maxDegreeOfParallelismForStreamResourcePages=3 --includeDescriptors=true --exclude=surveys

仅Ed-Fi ODS API v5.2注意：--exclude标志用于防止尝试移动任何调查数据，这是由于Ed-Fi ODS API v5.2版本中的安全元数据问题（在ODS-4974中描述）。如果删除此参数，发布操作将因数据中的依赖项未满足而失败。此问题已在ODS/API平台的后续版本中修复。

有关API Publisher参数的更多文档，请参阅API Publisher配置 markdown文件了解其他运行时选项。

有关键变更和删除的更多信息，请参阅键变更和删除的注意事项。

Ed-Fi ODS / API 5.1至5.3的已知限制

目前，Ed-Fi ODS / API 5.1至5.3存在以下与Change Queries和Ed-Fi API Publisher相关的已知问题。这些问题已在Ed-Fi ODS / API 5.3-cqe补丁和Ed-Fi ODS / API 6.1中解决。

• Change Queries实现未提供足够信息在ODS数据库之间传达删除操作
• 添加对Change Queries通过自然键跟踪删除的支持
• Change Queries不捕获派生资源的删除
• Change Queries不支持主键变更

（关于上述Ed-Fi ODS API问题解决需求的反馈，应通过Ed-Fi支持提供给Ed-Fi联盟。）

Ed-Fi ODS/API仅公开已删除资源的"Id"，但由于"Id"并非旨在作为资源的全局可移植标识符（Ed-Fi使用域键值作为标识），因此当前删除资源的实现对于API发布的价值有限。

即使通过公开主键值添加了删除支持，由于Ed-Fi ODS API（至少到v5.3）的内部实现细节，仍无法跟踪和发布Descriptors的删除。

源API中（支持主键变更的API资源上的）主键变更目前会导致目标API中保留资源"旧"版本的过时副本（以及所有受影响的依赖项）。

Ed-Fi API Publisher的另一个限制是当前不支持API Profiles（用于为API客户端定义资源/属性级别的数据策略）。如果对此感兴趣，请创建支持案例请求Profiles支持。

有关其中一些问题的更多技术细节，请参见此处。

后续步骤

准备深入了解时，请查看以下主题：

• API连接管理
• API Publisher配置
• API主机注意事项
• Docker配置和执行注意事项
• 如何使用TextFormatter类

支持

有关API Publisher的支持，请使用Ed-Fi支持提交支持案例和/或功能请求。

***信息

版权所有 (c) 2024 Ed-Fi Alliance, LLC及贡献者。

根据Apache License, Version 2.0（"许可证"）授权。

除非适用***要求或书面同意，否则根据许可证分发的软件按"原样"分发，不提供任何明示或暗示的担保或条件。请参阅许可证了解特定语言的权限和限制。

有关其他版权和许可通知，请参见NOTICES。