How to perform multiple content download

How to perform multiple content download

[tab:Actions]

Introduction

 

The multiple content download allow users to perform a multiple selection of content (can be all the content within a specific folder or a multiple selection of specific xcontentIds) and require their download in the form of a .zip archive. Supported content types are: IMAGE, VIDEO, AUDIO, PLAYLIST, DOCUMENT, PAGE. Content download can be performed in two different ways:

  • source file download: it can be performed only by those authenticated users having the "share" access right on the content to be downloaded.
  • transcoded asset download: it can be downloaded by any user if the content has been marked as "downloadable", or by any authenticated user who can download the source file (because they have "share" access right on the content).

 

How it works

 

Each content within THRON can have multiple channels and different qualities; in order to allow an easy access to content, the following rule has been applied: content will be always downloaded at the maximum available quality according to the user's access rights.

 

Multiple content download has two different phases:

  1. after the first request, the .zip file is prepared, providing the list of content which have to be downloaded. Users will be provided with a specific downloadId.
  2. the second request triggers the effective archive download. The archive is generated in real-time and it is delivered in streaming to the user performing the request.

 

Features

 

  • in a multiple selection, for all the content on which the user has the "share" access right, the source file will be downloaded; for all the "downloadable" content, the transcoded version at the maximum available quality will be downloaded; in any other case the content won't be included in the archive.
  • source file download is audited.
  • the tracking of the "content downloaded" event is handled server-side.
  • the .zip file is generated in real time, hence its download cannot be resumed in case of disconnection.
  • the .zip archive can include (if requested) a .manifest file which summarizes the mapping between filenames and xcontentIds.
  • In case of playlists, a folder will be included in the .zip archive, and within the folder users will find all the playlist's elements.

 

Prepare 

 

The web service which has to be invoked in order to prepare the .zip archive is prepare which is included in the archive package of xcontents. The URL of the request is structured as follows:

//[clientId]-extra.thron.com/api/xcontents/resources/archive/prepare/[clientId]

Parameters which have to be included among the headers of the request are:

  • X-TOKENID: a valid platform token related to a user or an application with required access rights.
  • clientId: the domain name used to access THRON, usually matches your company name.

 

In the body of the request you can paste the following JSON, filling required parameters:

{
  "criteria": {
    "linkedCategoryOp": {
      "linkedCategoryIds": [
        ""
      ],
      "cascade": false
    },
    "contentType": [
      ""
    ],
    "itagOp": {
      "itags": [
        {
          "id": "",
          "classificationId": ""
        }
      ],
      "operation": ""
    },
    "imetadataKeyOp": {
      "imetadata": [
        {
          "classificationId": "",
          "key": "",
          "value": ""
        }
      ]
    },
    "xcontentIds": [
      ""
    ]
  },
  "options": {
    "video": [
      ""
    ],
    "audio": [
      ""
    ],
    "other": [
      ""
    ],
    "image": [
      ""
    ],
    "locale": "",
    "appendManifestFile": false
  }
}

Where:

  • linkedCategoryIdsarray[string], optional; if provided, the archive will be generated starting from the content within the folder. In order to propagate the selection to all the subfolders you will just have to set the "cascade" parameter to true. Maximum 50 folders can be provided.
  • contentTypestring, optional; it can be used to filter content type to be downloaded.
  • itagOp: this object can be used in order to filter content selection according to tags. For each tag you will have to provide the id of the tag and the classificationId, maximum 5 tags can be provided. Use the operation parameter to specify if the filtering must be done using the "AND" or the "OR" operator.
  • imetadataKeyOp: this object can be used in order to filter content selection according to the presence of a specific key metadata. Maximum 5 key metadata can be provided.
  • xcontentIdsarray[string], optional; the list of content to be included in the archive. Maximum 1000 elements.
  • options: use this object to specify the content's format to be downloaded for each content type. It can be the source file, a specific channel, or (in case of IMAGE) a specific resolution. E.g.: "SOURCE", "WEB", "WEBHD", "1920x1024".
  • localestring, optional; use this parameter to save pages and playlist using the correct prettyId as name of the file.
  • appendManifestFileboolean, optional; set this parameter to true if you want to include the manifest file in the archive.

 

In the response of this request you will obtain a downloadId which has to be provided in order to download the archive.

IMPORTANTThe validity of the downloadId is limited over time, so you should avoid integrations where this value is stored for later use. The prepare service should only be invoked when the content have to be downloaded.

 

Download

 

The web service which has to be invoked in order to download the .zip archive is download which is included in the archive package of xcontents. The URL of the request is structured as follows:

//[clientId]-extra.thron.com/api/xcontents/resources/archive/download/[clientId]

The request must be performed using Content-Type: application/x-www-form-urlencoded. Form parameters are:

  • tokenIdstring, mandatory; a valid platform token related to a user or an application with required access rights.
  • downloadIdstring, mandatory; the downloadId obtained in the response of the prepare request.
  • saveAsstring, optional; the name for the .zip archive.
  • contactId: string, optional; the id of the contact to which you want to assign the download event of the archive.

 

Naming convention

 

Files included into the archive will respect the following naming convention:

 

Simple content (video, audio, immagine, other): [channel][fileName].[extension] where

  • channel: a reference to identify the downloaded channel:
    – "empty" if the original file is downloaded,
    – channel name (WEB,WEBHD...) if a transcoded version is downloaded,
    – divArea for IMAGE content type.
  • fileName: the name of the sourceFile regardless the file being downloaded (source file or transcoded version).
  • extension: the file's extension extracted from the mimeType of the resource.

 

Complex content (playlists or pagelets): [title].[extension] where

  • title: the prettyId in the specified language if available. If prettyId is not available, xcontentId will be used.
  • extension: .html for pagelet content .zip for playlist when downloaded individually.

 

Hybrid: When downloading both simple content and playlists together, the archive will contain one file for each content as described above, and one folder for each downloaded playlist whose name will be the prettyId of the playlist, if available, otherwise its xcontentId.

[/tab][tab:Code Samples] [dropdown:PHP - MULTIPLE DOWNLOAD]

<?php
/***
 * #################################################################################### 
 * @author stefano.bisello
 * @copyright 2016
 * ####################################################################################
 *
 * INFO
 * Howto create multiple download
 * WebService THRON: https://developer.thron.com/#!/archive/prepare
 * WebService THRON: https://developer.thron.com/#!/archive/download
 *
 * ####################################################################################
 * config
 * ####################################################################################
 */ 
    $client_idTHRON = 'CLIENT ID THRON';
    // login credential
    $tokenid="TOKEN ID";
    $arrayXcontentID=array("XCOTNENT ID1",
                       "XCOTNENT ID2",
                       "XCOTNENT ID3");
    $saveFileName="NAME OF THE ZIP FILE TO BE DOWNLOADED";

 //####################################################################################################################
 //MAIN
 //####################################################################################################################
    // prepare archive 
    $url = "http://".$client_idTHRON."-extra.thron.com/api/xcontents/resources/archive/prepare/".$client_idTHRON;    
    $header =  array(
                    'X-TOKENID: ' . $tokenid,
                    "Content-Type: application/json"
                    );
    $body = array("criteria" => array(                          
                                  "xcontentIds" => $arrayXcontentID                              
                                  ),
                 );     
    $request = json_encode($body);

        
    $curl = curl_init($url);
        
    curl_setopt($curl, CURLOPT_HEADER, true);
    curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
    curl_setopt($curl, CURLOPT_POSTFIELDS, $request);

    $curlRes = curl_exec($curl);
    
    $curlResInfo = curl_getinfo($curl);
    curl_close($curl);

    $resHeadersString = substr($curlRes, 0, $curlResInfo['header_size']);
    $resBody = substr($curlRes, $curlResInfo['header_size']);
    $response = json_decode($resBody,true);
    //#########################
    //get info reponse WS 
    //#########################
    if($response["resultCode"]!="OK")
    {
        echo "<br>Error generation archive:".$response['errorDescription']; 
        echo "<br>- resultCode:".$response['resultCode'];   ;   
        echo "<br>- errorDescription:".$response['errorDescription'];   ;   
        die("End script");  
    }
    //get downloadId
    $downloadId=$response['downloadId'];    
    //#########################
    //EXECUTE AND SAVE FILE DOWNLOAD ARCHIVE
    //######################### 
    $url = "http://".$client_idTHRON."-extra.thron.com/api/xcontents/resources/archive/download/".$client_idTHRON;   
    $header =  array(
            'X-TOKENID: ' . $tokenid,
            "Content-Type: application/x-www-form-urlencoded"
        );
    $body = "tokenId=".$tokenid."&downloadId=".$downloadId;     
        
    $curl = curl_init($url);
            curl_setopt($curl, CURLOPT_HEADER, true);
            curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($curl, CURLOPT_HTTPHEADER, $header);
            curl_setopt($curl, CURLOPT_POSTFIELDS, $body);
    $curlRes = curl_exec($curl);
        //echo $curlRes;
    $curlResInfo = curl_getinfo($curl);
    curl_close($curl);

    $resHeadersString = substr($curlRes, 0, $curlResInfo['header_size']);
    $resBody = substr($curlRes, $curlResInfo['header_size']);

    //save file to disk
    file_put_contents($saveFileName, $resBody);
?>

<!DOCTYPE html>
    <head>
        <meta charset="utf-8">
        <title>THRON API example with PHP</title>
    </head>
    <body>            
       <h1> Response action</h1>    
    <p><b><pre>RESULT:file <?php echo $saveFileName; ?> generate </pre></b></p>
<a href="<?php echo $saveFileName; ?>">Download archive</a> </body> </html>

[/dropdown]

[/tab]

Was this article helpful?
0 out of 0 found this helpful

Have more questions?

SUBMIT A REQUEST

Hai altre domande?

INOLTRA UNA RICHIESTA

Comments