README

使用场景

该库旨在用于第三方系统（例如 LMS、CMS）以与 edu-sharing 交互，以便将 edu-sharing 材料嵌入到其页面中。

先决条件

每个第三方系统都必须首先在 edu-sharing 中注册。为了使用此库，必须使用 edu-sharing 6.0 或更高版本。

要注册系统，以管理员身份登录到您的 edu-sharing，切换到 Admin-Tools -> Remote-Systems

Composer 使用（Beta）

如果您已经使用 composer，则可以将此库作为 composer 依赖项获取

composer require edu-sharing/auth-plugin 8.0.x-dev.

您可以访问 EduSharing 命名空间中的所有类。

有关包和可用版本的更多信息，请访问此处：https://packagist.org.cn/packages/edu-sharing/auth-plugin

如何注册您的应用程序？

注册通过向存储库（通过 XML 文件）提供公钥来处理。

您可以通过调用 php example/example.php 创建此类注册文件。它将创建一个 private.key 文件（请确保安全存储此文件，并且永远不要将其暴露给客户端！）。生成的 properties.xml 文件可以用于在 edu-sharing 中注册应用程序。（请参阅先决条件）（当使用 docker 时，此步骤不是必需的，它将自动执行）

基本工作流程和功能

有 2 种常见用例

1. 登录并选择要嵌入的对象

对于此工作流程，您首先需要调用 getTicketForUser，包括 userid 以获取您已认证用户的票据。由于您的应用程序通过公钥注册，我们将信任您的请求并返回票据（类似于用户会话）。

获得票据后，您将用户导航到 edu-sharing UI，以便他们可以选择元素。<base-url>/components/search?ticket=<ticket>&reurl=IFRAME

当用户选择了一个元素时，您将通过 JavaScript 接收到该特定元素。

window.addEventListener('message', receiveMessage, false);
function receiveMessage(event) {
    if (event.data.event === 'APPLY_NODE') {
        console.log(event.data.data);
    }
}

现在您需要使用 createUsage 方法来为此元素创建持久的使用。

将您从该方法接收到的数据持久化，以便稍后显示。

完整的工作示例在 example/index.html 中给出（您需要先注册您的应用程序，见上文）

检查 docker-compose.yml 文件中的 BASE_URL 变量。然后在 example 文件夹中运行 docker compose build && docker compose up -d，然后打开 https://:8080/example。

2. 渲染/显示先前嵌入的对象

如果您先前为对象生成了使用数据，则可以获取它以进行显示/渲染。只需调用包括先前收到的使用数据的 getNodeByUsage。

您将获得完整的节点对象（请参阅 REST 规范）以及一个可用于嵌入的 HTML 片段（detailsSnippet）。

2.1 内容 + 下载链接，预览

由于您收到的对象可能不是公开可用的，您需要生成特定的 URL 以通过当前使用访问它。

您需要在您的应用程序中创建一个单独的端点，该端点验证当前用户的访问权限，然后将其重定向到 edu-sharing。

在初始化库时，配置此端点在您的应用程序中可用的路径，例如

$nodeHelper = new EduSharingNodeHelper($base,
    new EduSharingNodeHelperConfig(
        new UrlHandling(true, 'my/api/redirect/endpoint')
    )
);

然后，此端点应验证用户权限并调用库的redirect方法

        $url = $nodeHelper->getRedirectUrl(
            $_GET['mode'],
            new Usage(
                $_GET['nodeId'],
                $_GET['nodeVersion'] ?? null,
                $_GET['containerId'],
                $_GET['resourceId'],
                $_GET['usageId'],
            )
        );
        header("Location: $url");

此方法将创建一个带有当前时间戳的签名URL，然后允许用户临时访问给定的对象。

从getNodeByUsage返回的urls部分已针对您指定的端点URL。

对于预览图像，有getPreview方法，它将返回图像的二进制数据。

常见问题解答

什么是使用权限？

使用权限是指特定元素的信息和访问权限。

使用权限可以由注册的应用程序创建。之后，此使用权限将允许该应用程序在任意时间获取给定元素，无需额外权限。

在通过使用信息获取元素之前，我需要票据/已登录的用户吗？

不需要。元素只需要有使用权限。使用权限将允许您的应用程序访问此元素。edu-sharing将“信任”您的应用程序仅获取您确保当前用户应有权访问的元素（例如，特定页面或课程）。

我可以在没有票据/已登录用户的情况下创建使用权限吗？

不能。为了创建使用权限，我们首先需要确保想要生成该权限的用户对给定元素有适当的权限。因此，我们需要票据来确认用户状态。此外，用户信息还将存储在使用权限中。

我如何找出元素是否已具有使用权限？

在edu-sharing中，具有适当权限的情况下，右键单击并选择“邀请”。在“受邀”部分，您还将看到使用权限列表，也可以为特定元素“撤销”使用权限。

我需要为公开元素使用使用权限吗？

从理论上讲：不需要。因为元素对每个人都是可访问的，所以从权限角度来看，不需要使用权限。

然而，我们使用使用权限进行跟踪/统计目的。此外，节点可能在未来的某个时刻变得私密，这将破坏任何远程嵌入。因此，您应该始终创建使用权限。

高级使用

自定义Curl处理器

如果您正在工作的系统已经提供了curl实现（例如，用于全局配置代理、重定向或其他功能），您可能希望通过现有实现路由此库的所有请求。

在这种情况下，您可以附加自定义curl处理器。请注意，您必须在实例化基本库后直接这样做，否则某些请求可能已经发送。

$base->registerCurlHandler(new class extends CurlHandler {

    public function handleCurlRequest(string $url, array $curlOptions): CurlResult
    {
       return new CurlResult('', 0, []);
    }
});

请查看curl.php文件以获取更多详细信息及示例。

手动/自定义实现注意事项

如果您无法使用库或需要在其他编程语言中实现edu-sharing集成，以下是一些一般性提示。

添加签名头

对于您将向我们的API发出的每个请求，您都需要添加以下头信息

X-Edu-App-Id: <your-app-id>,
X-Edu-App-Signed: <signed-payload-including-the-timestamp>,
X-Edu-App-Sig: <signature>,
X-Edu-App-Ts: <unix-timestamp-in-ms>,

签名必须使用您的私钥生成（其中公钥为edu-sharing存储库所知），在PHP中，它将像这样完成

$privateKeyId = openssl_get_privatekey($privateKey);
openssl_sign($toSign, $signature, $privateKeyId);
return base64_encode($signature);

在Java中，它将是

Signature dsa = Signature.getInstance(ALGORITHM_SIGNATURE);
dsa.initSign(privateKey);
dsa.update(data.getBytes());
byte[] signature = dsa.sign();
return new Base64().encode(signature);

获取票据

通过调用获取票据（您可以在以后用作用户的身份验证）

GET /rest/authentication/v1/appauth/<username>

请记住，按照前面所述附加签名头。

创建使用权限

通过调用创建使用权限

POST /rest/usage/v1/usages/repository/-home-

包括（JSON）有效负载

{
  "appId": "<your-app-id>",
  "courseId": "<container-id>",
  "resourceId": "<resource-id>",
  "nodeId": "<node-id>",
  "nodeVersion": "<node-version>"
}

以及以下头信息，包括之前获取的用户票据

Authorization: EDU-TICKET <ticket>

想了解更多关于此有效负载的个体数据，请参阅此库中 createUsage 方法的代码文档。

通过使用来获取元素

通过调用以下方法来获取之前生成的使用情况：

GET /rest/rendering/v1/details/-home-/<usage-node-id>

并添加以下HTTP头信息

X-Edu-Usage-Node-Id: <usage-node-id>
X-Edu-Usage-Course-Id: <usage-container-id>
X-Edu-Usage-Resource-Id: <usage-resource-id>
X-Edu-User-Id: <user-id> # optional

edu-sharing / auth-plugin

维护者

详细信息