Skip to content

OcEventsApi

Jump to bottom
FarbodZamani edited this page Apr 19, 2023 · 10 revisions

This class contains all REST API calls to the /api/events endpoint.

Namespace

It is accessible under OpencastApi\Rest namespace.

How to use

  1. In OpencastApi\OpenCast as its property with OpenCast properties naming convention:
use OpencastApi\OpenCast;
$opencastApi = new OpenCast($config);
$ocEventsApi = $opencastApi->eventsApi;
...
  1. Direct instantiation:
use OpencastApi\Rest\OcRestClient;
use OpencastApi\Rest\OcEventsApi;
$ocRestClient = new OcRestClient($config);
$ocEventsApi = new OcEventsApi($ocRestClient);
...

Functions

Consumable functions are liested below:

getAll($params = [])

Returns the list of events. More Detail

  • $params is an optional array that could contain the following:
[
     'sign' => (boolean) {Whether public distribution urls should be signed.},
     'withacl' => (boolean) {Whether the acl metadata should be included in the response.},
     'withmetadata' => (boolean) {Whether the metadata catalogs should be included in the response. },
     'withscheduling' => (boolean) {Whether the scheduling information should be included in the response. (version 1.1.0 and higher)},
     'withpublications' => (boolean) {Whether the publication ids and urls should be included in the response.},
     'onlyWithWriteAccess' => (boolean) {Whether only to get the events to which we have write access.},
     'sort' => (array) {an assiciative array for sorting e.g. ['title' => 'DESC']},
     'limit' => (int) {the maximum number of results to return},
     'offset' => (int) {the index of the first result to return},
     'filter' => (array) {an assiciative array for filtering e.g. ['is_part_of' => '{series id}']},
]
  • Returns an array: ['code' => 200, 'body' => 'A (potentially empty) array list of events is returned.']

getBySeries($seriesId, $params = [])

Returns a list of events for specified series. More Detail

  • $seriesId the identifier for a series
  • $params is an optional array that could contain the following:
[
     'sign' => (boolean) {Whether public distribution urls should be signed.},
     'withacl' => (boolean) {Whether the acl metadata should be included in the response.},
     'withmetadata' => (boolean) {Whether the metadata catalogs should be included in the response. },
     'withscheduling' => (boolean) {Whether the scheduling information should be included in the response. (version 1.1.0 and higher)},
     'withpublications' => (boolean) {Whether the publication ids and urls should be included in the response.},
     'onlyWithWriteAccess' => (boolean) {Whether only to get the events to which we have write access.},
     'sort' => (array) {an assiciative array for sorting e.g. ['title' => 'DESC']},
     'limit' => (int) {the maximum number of results to return},
     'offset' => (int) {the index of the first result to return},
     'filter' => (array) {an assiciative array for filtering e.g. ['is_part_of' => '{series id}']},
]
  • Returns an array: ['code' => 200, 'body' => 'A (potentially empty) array list of events in a series is returned.']

get($eventId, $params = [])

Returns a single event. More Detail

  • $eventId the identifier of the event.
  • $params is an optional array that could contain the following:
[
    'sign' => (boolean) {Whether public distribution urls should be signed.},
    'withacl' => (boolean) {Whether the acl metadata should be included in the response.},
    'withmetadata' => (boolean) {Whether the metadata catalogs should be included in the response. },
    'withscheduling' => (boolean) {Whether the scheduling information should be included in the response. (version 1.1.0 and higher)},
    'withpublications' => (boolean) {Whether the publication ids and urls should be included in the response.}
]
  • Returns an array: ['code' => 200, 'body' => 'The event (Object)']

create($acls, $metadata, $processing, $scheduling = '', $presenterFile = null, $presentationFile = null, $audioFile = null, $progressCallable = null)

Creates an event. More Detail

  • $acls (string|array) A collection of roles with their possible action.
  • $metadata (string|array) Event metadata
  • $processing (string|array) Processing instructions task configuration
  • $scheduling (string|array) (optional) Scheduling information (version 1.1.0 and higher)
  • $presenterFile (file) (optional) Presenter movie track
  • $presentationFile (file) (optional) Presentation movie track
  • $audioFile (file) (optional) Audio track
  • $progressCallable (callable) (optional) Defines a function to invoke when transfer progress is made. The function accepts the following positional arguments:
function (
     $downloadTotal: the total number of bytes expected to be downloaded, zero if unknown,
     $downloadedBytes: the number of bytes downloaded so far,
     $uploadTotal: the total number of bytes expected to be uploaded,
     $uploadedBytes: the number of bytes uploaded so far
)
  • Returns an array: ['code' => 201, 'body' => '{A new event is created and its identifier is returned}', 'location' => '{the url of new event'}]

update($eventId, $acls = '', $metadata = '', $processing = '', $scheduling = '', $presenterFile = null, $presentationFile = null, $audioFile = null)

Updates an event. More Detail

  • $eventId (string) the event identifier.

  • $acls (string|array) (optional) A collection of roles with their possible action.

  • $metadata (string|array) (optional) Event metadata

  • $processing (string|array) (optional) Processing instructions task configuration

  • $scheduling (string|array) (optional) Scheduling information (version 1.1.0 and higher)

  • $presenterFile (file) (optional) Presenter movie track

  • $presentationFile (file) (optional) Presentation movie track

  • $audioFile (file) (optional) Audio track

  • Returns an array: ['code' => 204, 'reason' => 'NO CONTENT'] {The event has been updated}

delete($eventId)

Retracts possible publications and deletes an event. More Detail

  • $eventId (string) the event identifier.

  • Returns an array: ['code' => 204, 'reason' => 'NO CONTENT'] (The event has been deleted)

getAcl($eventId)

Returns an event's access policy. More Detail

  • $eventId (string) the event identifier.

  • Returns an array: ['code' => 200, 'body' => '{The access control list for the specified event (Object)}']

updateAcl($eventId, $acl)

Returns an event's access policy. More Detail

  • $eventId (string) the event identifier.

  • $acl (string|array) Access policy.

  • Returns an array: ['code' => 204, 'reason' => 'NO CONTENT'] (The access control list for the specified event is updated)

emptyAcl($eventId)

Removes all ACLs for the event. Basically it is an updateAcl call but with an empty acl list array More Detail

  • $eventId (string) the event identifier.

  • Returns an array: ['code' => 204, 'reason' => 'NO CONTENT'] (The access control list for the specified event is updated)

addSingleAcl($eventId, $action, $role)

Grants permission to execute action on the specified event to any user with role role. More Detail

  • $eventId (string) the event identifier.

  • $action (string) The action that is allowed to be executed.

  • $role (string) The role that is granted permission.

  • Returns an array: ['code' => 204, 'reason' => 'NO CONTENT'] (The permission has been created in the access control list of the specified event)

deleteSingleAcl($eventId, $action, $role)

Revokes permission to execute action on the specified event from any user with specified role. More Detail

  • $eventId (string) the event identifier.

  • $action (string) The action that is no longer allowed to be executed.

  • $role (string) The role that is no longer granted permission.

  • Returns an array: ['code' => 204, 'reason' => 'NO CONTENT'] (The permission has been revoked from the access control list of the specified event)

getMedia($eventId)

Returns the complete set of media tracks. More Detail

  • $eventId (string) the event identifier.

  • Returns an array: ['code' => 200, 'body' => '{The list of media tracks is returned}']

addTrack($eventId, $flavor, $track, $overwriteExisting = false)

Adds the given track to the given flavor in the event. It does not start a workflow. More Detail (From v1.3.0)

  • $eventId (string) the event identifier.

  • $flavor (string) Denotes type and subtype, e.g. 'captions/source+en'

  • $track (file stream) The track file

  • $overwriteExisting (boolean) If true, all other tracks in the specified flavor are REMOVED (Default: false)

  • Returns an array: ['code' => 200, 'reason' => 'NO CONTENT'] (The track was added successfully.)

getMetadata($eventId, $type = '')

Returns the event's metadata (if type is defined of the specified type). More Detail

  • $eventId (string) the event identifier.

  • $type (string) (optional) The type of metadata to get.

  • Returns an array: ['code' => 200, 'body' => '{The metadata collection (array)}']

updateMetadata($eventId, $type, $metadata)

Update the metadata with the matching type of the specified event. More Detail

  • $eventId (string) the event identifier.

  • $type (string) The type of metadata to update.

  • $metadata (string|array) Event metadata.

  • Returns an array: ['code' => 200, 'reason' => 'OK'] (The metadata of the given namespace has been updated)

deleteMetadata($eventId, $type)

Delete the metadata namespace catalog of the specified event. More Detail

  • $eventId (string) the event identifier.

  • $type (string) The type of metadata to delete.

  • Returns an array: ['code' => 204, 'reason' => 'No Content'] (The metadata of the given namespace has been delete)

getPublications($eventId, $sign = false)

Returns an event's list of publications. More Detail

  • $eventId (string) the event identifier.

  • $sign (boolean) (optional) Whether publication urls (version 1.7.0 or higher) and distribution urls should be pre-signed.

  • Returns an array: ['code' => 200, 'body' => '{The list of publications}']

getSinglePublication($eventId, $publicationId ,$sign = false)

Returns a single publication. More Detail

  • $eventId (string) the event identifier.

  • $publicationId (string) the publication id.

  • $sign (boolean) (optional) Whether publication urls (version 1.7.0 or higher) and distribution urls should be pre-signed.

  • Returns an array: ['code' => 200, 'body' => '{The track details}']

getScheduling($eventId)

Returns an event's scheduling information. (Available since API version 1.1.0) More Detail

  • $eventId (string) the event identifier.

  • Returns an array: ['code' => 200, 'body' => '{The scheduling information for the specified event}']

updateScheduling($eventId, $scheduling, $allowConflict = false)

Update the scheduling information of the event. (Available since API version 1.1.0) More Detail

  • $eventId (string) the event identifier.

  • $scheduling (string|array) The scheduling information.

  • $allowConflict (boolean) (optional) Allow conflicts when updating scheduling.

  • Returns an array: ['code' => 204, 'reason' => 'NO CONTENT'] (The scheduling information for the specified event is updated)

Clone this wiki locally