README

这个 PHP Composer 包旨在提供一个统一的、易于使用的 Opencast RESTful API 库。它被设计用来使第三方应用程序（如 Stud.IP、Moodle 和 ILIAS）的开发者能够使用大多数常用的 REST Endpoints。有关更多信息，请参阅变更日志。

注意

从版本 1.2.0 开始，主类名已从 OpenCast 更改为 OpenCast。有关更多信息，请参阅升级日志。

需求

PHP 版本 7.2.5 或更高版本 以及 cURL 是必需的。此外，必须满足guzzlehttp/guzzle的要求。

安装

composer require elan-ev/opencast-api

基本用法

使用此库中的 Opencast REST Endpoints 有两种方法

第一种是使用通用的 OpencastApi\Opencast，它包含所有可用的 Opencast Endpoints（这些端点具有配置中定义的 API 版本的能力）。使用这种方法的优势是能够更好地控制所有可用的端点。（推荐）

注意：当使用此库针对具有管理员和展示分离的分布式 Opencast 设置时，可以在实例化 OpencastApi\Opencast 时作为第二个参数传递另一组配置。最初，展示节点仅负责搜索端点。

$config = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API Version. (Default null). (optional)
      'handler' => null                               // The callable Handler or HandlerStack. (Default null). (optional)
      'features' => null                              // A set of additional features [e.g. lucene search]. (Default null). (optional)
];

$engageConfig = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API version. (Default null). (optional)
      'handler' => null                               // The callable Handler or HandlerStack. (Default null). (optional)
      'features' => null                              // A set of additional features [e.g. lucene search]. (Default null). (optional)
];

use OpencastApi\Opencast;

// In case of a distributed Opencast setup
$opencastDualApi = new Opencast($config, $engageConfig);
// Or simply
$opencastApi = new Opencast($config);

// Accessing Event Endpoints to get all events
$events = [];
$eventsResponse = $opencastApi->eventsApi->getAll();
if ($eventsResponse['code'] == 200) {
      $events = $eventsResponse['body'];
}

// Accessing Series Endpoints to get all series
$series = [];
$seriesResponse = $opencastApi->seriesApi->getAll();
if ($seriesResponse['code'] == 200) {
      $series = $seriesResponse['body'];
}

// ...

第二种方法是在需要时实例化位于 OpencastApi\Rest\ 命名空间下的每个 REST 端点类，但这种方法的不利之处在于它需要一个 OpencastApi\Rest\OcRestClient 实例作为其参数。这种方法的优势可能是 IDE 中的方法定义。

$config = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API version. (Default null). (optional)
      'handler' => null                               // The callable Handler or HandlerStack. (Default null). (optional)
      'features' => null                              // A set of additional features [e.g. lucene search]. (Default null). (optional)
];


use OpencastApi\Rest\OcRestClient;
use OpencastApi\Rest\OcEventsApi;
use OpencastApi\Rest\OcSeriesApi;

// Get a client object.
$opencastClient = new OcRestClient($config);

// To get events.
$opencastEventsApi = new OcEventsApi($opencastClient);
$events = [];
$eventsResponse = $opencastEventsApi->getAll();
if ($eventsResponse['code'] == 200) {
      $events = $eventsResponse['body'];
}

// To get series.
$opencastSeriesApi = new OcSeriesApi($opencastClient);
$series = [];
$seriesResponse = $opencastSeriesApi->getAll();
if ($seriesResponse['body'] == 200) {
      $series = $seriesResponse['body'];
}

// ...

配置

配置是 Array 类型，必须按照以下方式定义

$config = [
      'url' => 'https://develop.opencast.org/',       // The API URL of the Opencast instance. (required)
      'username' => 'admin',                          // The API username. (required)
      'password' => 'opencast',                       // The API password. (required)
      'timeout' => 0,                                 // The API timeout. In seconds (default 0 to wait indefinitely). (optional)
      'connect_timeout' => 0,                         // The API connection timeout. In seconds (default 0 to wait indefinitely) (optional)
      'version' => null,                              // The API version. (Default null). (optional)
      'handler' => null                               // The callable Handler or HandlerStack. (Default null). (optional)
      'features' => null                              // A set of additional features [e.g. lucene search]. (Default null). (optional)
];

更新（v1.7.0）：配置数组中添加了新的项 features。目前，它被用来处理切换行为，可以通过添加 'features' => ['lucene' => true] 简单地启用/禁用 Lucene 搜索端点。请记住，该端点默认是关闭的，并且从 Opencast 16 开始将不起作用。因此，开发者必须非常小心地使用此功能并切换它！

注意：负责搜索的展示（engage 节点）的配置必须与正常配置相同。但在任何参数缺失的情况下，其值将来自主要配置参数。

额外：动态地将摄取端点类加载到 Opencast 实例中。

从 v1.3 版本开始，可以通过将布尔值作为类的最后一个参数传递来启用（默认）或禁用是否将摄取端点加载到 OpencastApi\Opencast 中。

use OpencastApi\Opencast;
$opencastApiWithIngest = new Opencast($config, $engageConfig);
$opencastApiWithoutIngest = new Opencast($config, $engageConfig, false);
// ...

响应

每次调用的返回结果都是一个包含以下信息的 Array：从 v1.4 版本开始，第 5 个响应参数 'origin' 可用！

[
      'code' => 200,                            // The status code of the response
      'body' => '',                             // The result of the response. It can be type of string, array or objec ('' || [] || {})
      'reason' => 'OK',                         // The reason/message of response
      'location' => '',                         // The location header of the response when available,
      'origin' => [                             // The information about the origin of the request (ADDED in v1.4)
            'base' => 'https://example.com',    // Request base url address
            'path' => '/api/path',              // Request url path
            'method' => 'GET',                  // Request method
            'params' => [                       // Request parameters
                'query_params' => [],
                'form_params' => [],
                'form_multipart_params' => [],
                'json' => [],
                'body' => null,
            ]
      ]
]

过滤器排序

过滤器排序必须定义为如下的关联 Array

// for example:

$filters = [
      'title' => 'The title name',
      'creator' => 'opencast admin'
];

$sorts = [
      'title' => 'DESC',
      'startDate' => 'ASC'
];

注意：有时一个过滤器可以多次出现，例如在系列 API /get中，如 subject 和 identifier 这样的过滤器可以多次出现。因此，应像以下那样传递一个 Array 作为过滤器值：

// for example:

$filters = [
      'identifier' => [
            '{first ID}',  '{second ID}'
      ],
      'subject' => [
            '{first Subject}',  '{second Subject}'
      ]
];

`runWithRoles([])`

有时需要使用一个包含一些角色（例如用户ID）的可丢弃头 X-RUN-WITH-ROLES 来执行请求，以便Opencast假定这些用户具有特殊访问权限。
通常用于获取数据，例如使用onlyWithWriteAccess参数来执行OcSeriesApi中的getAll，并获取仅指定用户可以访问的系列！
为了执行此类请求，需要在类中调用所需功能之前调用 runWithRoles 方法。
注意：此方法接受一个定义要检查的角色的 Array！

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

// Role
$roles = ['ROLE_ADMIN'];
$seriesResponse = $opencastApi->seriesApi->runWithRoles($roles)->getAll(['onlyWithWriteAccess' => true]);

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocSeriesApi = \OpencastApi\Rest\OcSeriesApi($opencastClient);
// Role
$roles = ['ROLE_ADMIN'];
$seriesResponse = $ocSeriesApi->runWithRoles($roles)->getAll(['onlyWithWriteAccess' => true]);

注意：角色可以是包含每个角色的 Array，也可以是逗号分隔的字符串！

`runAsUser($user)`

有时需要使用包含用户ID的可丢弃头 X-RUN-AS-USER 来执行请求，以便Opencast假定此用户具有访问权限。此功能自v1.4起添加。注意：此方法接受一个定义要检查的用户ID的 String！

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

// Role
$user = 'lms-admin';
$seriesResponse = $opencastApi->seriesApi->runAsUser($user)->getAll(['onlyWithWriteAccess' => true]);

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocSeriesApi = \OpencastApi\Rest\OcSeriesApi($opencastClient);
// Role
$user = 'lms-admin';
$seriesResponse = $ocSeriesApi->runAsUser($user)->getAll(['onlyWithWriteAccess' => true]);

`noHeader()`

为了执行到端点的请求调用，无需任何请求头/选项，您可以在调用端点类中的所需功能之前使用此方法：注意：此方法接受什么也不（void）。

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

$baseResponse = $opencastApi->baseApi->noHeader()->get();

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocBaseApi = \OpencastApi\Rest\OcBaseApi($opencastClient);
$baseResponse = $ocBaseApi->noHeader()->get();

`setRequestTimeout($timeout = 0)`

为了执行带有不同超时值的请求调用，而不是配置中设置的值，您可以在调用端点类中的所需功能之前使用此方法：注意：此方法接受定义单个使用超时的整数值（秒）。

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

$baseResponse = $opencastApi->baseApi->setRequestTimeout(10)->get();

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocBaseApi = \OpencastApi\Rest\OcBaseApi($opencastClient);
$baseResponse = $ocBaseApi->setRequestTimeout(10)->get();

`setRequestConnectionTimeout($connectionTimeout = 0)`

为了执行带有不同连接超时值的请求调用，而不是配置中设置的值，您可以在调用端点类中的所需功能之前使用此方法：注意：此方法接受定义单个使用连接超时的整数值（秒）。

// With Opencast generic class
use OpencastApi\Opencast;
$opencastApi = new Opencast($config);

$baseResponse = $opencastApi->baseApi->setRequestConnectionTimeout(10)->get();

// Or direct class call
$opencastClient = \OpencastApi\Rest\OcRestClient($config);
$ocBaseApi = \OpencastApi\Rest\OcBaseApi($opencastClient);
$baseResponse = $ocBaseApi->setRequestConnectionTimeout(10)->get();

可用的Opencast REST服务端点

/api/*：此库中可用所有已知的Opencast API端点。 API端点定义WiKi
/ingest/*：所有已知的Ingest端点都可用。 Ingest端点定义WiKi
/services/services.json：只有services.json可用。 Services端点定义WiKi
/search/{episode | lucene | series}.{json | xml}：只有JSON或XML格式中的episode、lucene和series可用。 Search端点定义WiKi
/capture-admin/*：所有已知的Capture Admin端点都可用。 Capture Admin端点定义WiKi
/admin-ng/event/delete：只有delete端点可用。 Admin Ng端点定义WiKi
/recordings/*：所有已知的Recording端点都可用。 Recordings端点定义WiKi
/series/*：所有已知的Series端点都可用。 Series端点定义WiKi
/workflow/*：所有已知的Workflow端点都可用。 Workflow端点定义WiKi
/sysinfo/bundles/version：（v1.1.1）只有bundle version端点可用。 Sysinfo端点定义WiKi

模拟响应

为了进行适当的测试，提供了一种模拟机制。

如何使用

步骤 1：响应数组

在第一步中，需要将所有响应以数组形式呈现，该数组必须具有以下结构

$responsesArray = [
      "/api/events" => [ // Request Path
            "GET": [ // METHOD
                  [
                        "body" => "", //Response body (Default "")
                        "status": 200, // Status code (Default 200)
                        "headers": [], // Response headers (Default [])
                        "version": "", // Protocol version (Default null)
                        "reason": "", // Reason phrase (when empty a default will be used based on the status code) (Default null)
                        "params": []  // The optional params to pass to the call (Default [])
                  ]
            ],
            "POST": [ // METHOD
                  [
                        "body" => "", //Response body (Default "")
                        "status": 200, // Status code (Default 200)
                        "headers": [], // Response headers (Default [])
                        "version": "", // Protocol version (Default null)
                        "reason": "", // Reason phrase (when empty a default will be used based on the status code) (Default null)
                        "params": []  // The optional params to pass to the call (Default [])
                  ],
                  [...] // Multiple response data object to have multiple calls to the same path and same method. Please see the NOTE below.
            ],
            "PUT": [
                  [...]
            ],
            "DELETE": [
                  [...]
            ]
      ],
];

注意：为了对同一路径应用多个调用，必须在 params 数组中提供一个唯一的参数 unique_request_identifier，例如，您希望使用相同的路径更新系列 acl 两次，但 acl 值不同：（唯一标识符的值必须在请求体中）

$responsesArray = [
      "/api/series/{series id}/acl": [
            "PUT": [ // PUT METHOD on the same path
                  [
                        "body" => "", //Response body (Default "")
                        "status": 200, // Status code (Default 200)
                        "params": [  // The optional params to pass to the call (Default [])
                              "unique_request_identifier": "acl=[]"
                        ],
                  ],
                  [
                        "body" => "[{\"allow\":true,\"role\":\"ROLE_ANONYMOUS\",\"action\":\"read\"}]", //Response body (Default "")
                        "status": 200, // Status code (Default 200)
                        "params": [  // The optional params to pass to the call (Default [])
                              "unique_request_identifier": "ROLE_ANONYMOUS"
                        ],
                  ]
            ]
      ],
];

步骤 2：创建新的 MockHandler 实例并将其传递到配置数组中。

为了创建新的 MockHandler 实例，您应使用 \OpencastApi\Mock\OcMockHanlder::getHandlerStackWithPath 并将实例以处理器键的形式传递到配置数组中，如下所示

$mockResponses = [...]; // As described above.
$mockHandler = \OpencastApi\Mock\OcMockHanlder::getHandlerStackWithPath($mockResponses);

$config = [/*the config*/];
$config['handler'] = $mockHandler;
$opencast = new \OpencastApi\Opencast($config);

额外：记录请求 URI

如果您想要请求 URI 的列表，可以将文件路径变量作为 \OpencastApi\Mock\OcMockHanlder::getHandlerStackWithPath 的第二个参数传递，以将每个 URI 写入/追加到该文件中，如下所示；

$filePath = '{A valid writeable file path}';
$mockResponses = [...]; // As described above.
$mockHandler = \OpencastApi\Mock\OcMockHanlder::getHandlerStackWithPath($mockResponses, $filePath);

$config = [/*the config*/];
$config['handler'] = $mockHandler;
$opencast = new \OpencastApi\Opencast($config);

命名规范

类

除了 'Opencast' 类之外，OpencastApi\Rest\ 命名空间下的所有其他类都以 Oc 开头，后跟名称和端点类别。例如

OcEventsApi 包含 3 部分，包括 Oc + 端点名称（Events）+ 端点类别（Api）
OcServices 包含 2 部分，包括 Oc + 端点名称/类别（Services）

Opencast 类属性

访问来自 OpencastApi\Opencast 的端点子类的命名规范，包括不带 Oc 的类名，并以驼峰式格式表示。例如

use OpencastApi\Opencast;
$config = [/*the config*/];
$opencast = new Opencast($config);

// Accessing OcEventsApi would be like: (without Oc and in camelCase format)
$ocEventsApi = $opencast->eventsApi;

elan-ev / opencast-api

维护者

详细信息