About the Administration API

Use the Administration API to monitor, manage, and configure the server from an Adobe Flash Player or Adobe AIR client over RTMP or RTMPE or from a web client over HTTP. The Adobe Media Server Administration Console was built using the Administration API. The API is documented in Adobe Media Server Administration API Reference.

Here are a few important tips for working with the Administration API:

  • Both Adobe Media Server and Adobe Media Administration Server must be running.

  • This document assumes that you have not changed the default port number (1111) for the Administration Server; if you have, use your valid port number in all examples.

  • If you do not specify an optional parameter, a default value may be used depending on the method. For example, if you do not specify a virtual host in the scope parameter, it is assumed that you want to perform the command on the virtual host to which you connected when you logged in to Adobe Media Server.

  • By default, administrators are logged in to the “_defaultRoot_” adaptor. When logging in to a virtual host not on the default adaptor, virtual-host administrators must specify the name of the adaptor. For example, when logging in (over RTMP using NetConnection) to a virtual host on the adaptor _secondAdaptor_, the administrator JLee would enter the following information for the administrator user name parameter in the method call: _secondAdaptor_/JLee.

Set permissions for Administration API method calls over HTTP

Note:

You do not need to set permissions to call methods over RTMP.

  1. Open the ams.ini file in the RootInstall/conf folder.

  2. Make sure that the USERS.HTTPCOMMAND_ALLOW parameter is set to true.

  3. Open the Users.xml file in the RootInstall/conf folder.

  4. In the <Allow> element, enter method names in a comma-delimited list to allow HTTP requests to execute Administration API calls. For example, the following code allows the ping() and changePswd() methods:

     <AdminServer> 
         <HTTPCommands> 
             <Enable>${USERS.HTTPCOMMAND_ALLOW}/Enable> 
             <Allow>ping,changePswd</Allow> 
             <Deny>All</Deny> 
             <Order>Deny,Allow</Deny> 
         </HTTPCommands> 
     </AdminServer>

    Note:

    There are additional XML elements in the Users.xml file that give you finer control over permissions. For more information, see XML configuration files reference.

  5. Save the file and restart Adobe Media Administration Server.

Call an Administration API method over HTTP

  1. Verify that Adobe Media Administration Server is running.

  2. Open a browser window and enter the following in the address bar:

     http://localhost:1111/admin/ping?auser=username&apswd=password

    If the web browser is on a different computer than Adobe Media Server, use the server address instead of localhost. Substitute your administrator user name and password, which are located in the ams.ini file.

    Note:

    You can construct an Administration API call from any language that can send HTTP requests. This example uses a web browser because it’s the simplest client and good for testing purposes.

  3. The server sends the XML results back to the browser:

     <?xml version="1.0" encoding="utf-8" ?> 
     <result> 
         <level>status</level> 
         <code>NetConnection.Call.Success</code> 
         <timestamp>10/3/2007 05:31:01 PM</timestamp> 
     </result>

Constructing an HTTP request string

Many Administration APIs expect one or more parameters in addition to auser and apswd. Parameters passed in an HTTP request must adhere to the following formatting rules:

  • Name the parameters in the string. For example, the following code calls the addAdmin() method:

    http://localhost:1111/admin/addAdmin?auser=adminname&apswd=adminpassword&username="joe"&password="pass123"&vhost="_defaultRoot_/foo.myCompany.com"
  • Strings are passed as literals surrounded by quotation marks. You can use either single quotation marks (') or double quotation marks (").

    "Hello World"

    'String2'

    The only exceptions are the auser and apswd parameters, which should be passed without quotation marks.

  • Numbers are passed as either integer or floating-point literals.

    245

    1.03

    -45

    Note: When a number is used for an application name, the application name must be included within quotation marks (" ") for methods such as reloadApp() and unload App() to work properly.

  • Arrays are passed as comma-separated values enclosed in square brackets.

    [1,2,3,4]

    ['abcd',34,"hi"]

    [10,20,[31,32],40]

  • Objects are passed as inline object literals.

    {foo:123,bar:456}

    {user:"Joe",ssn:"123-45-6789"}

Call Administration API methods over RTMP or RTMPE

To call the Administration API over RTMP or RTMPE, you need a Flash Player or AIR client.

Note:

To call the Administration API over RTMPE, follow the instructions below, but change the protocol in the example NetConnection.connect() call to RTMPE.

  1. In the client application, create a NetConnection to Adobe Media Administration Server, passing in three parameters: the URI of the Administration Server, an administrator user name, and an administrator password. Only valid administrators, as defined in the Users.xml configuration file, can connect to the server.

    The following code creates a NetConnection for the administrator MHill with password 635xjh27 to the server on localhost:

     ncAdmin = new NetConnection(); 
    ncAdmin.connect("rtmp://localhost:1111/admin", "MHill", "635xjh27");

    Note:

    If you want to connect to a virtual host, specify the virtual host’s domain name or IP address as part of the URI—for example, rtmp://www.myVhost.com/admin:1111.

  2. Call the NetConnection.call() method and pass it the Administration API method, a response object (if needed) and any parameters (if needed):

     ncAdmin.call("getAppStats", new onGetAppStats(), "vod");

    The getAppStats() method returns performance data for an application running on the server; the response object onGetAppStats() captures the result of the call; and vod is the name of the application instance from which to retrieve statistics.

  3. Define a function to handle the information object returned by the Administration API method; in this example, onGetAppStats():

    ncAdmin.call("getAppStats", new onGetAppStats(), appName.text); 
    ... 
    function onGetAppStats(){ 
        this.onResult = function(info){ 
            if (info.code != "NetConnection.Call.Success"){ 
                outputBox.text = "Call failed: " + info.description; 
            } else { 
                outputBox.text = "Info for "+appName.text+ " returned:" + newline; 
                printObj(info, outputBox); 
            } 
        } 
    }

    The data is returned to the handler function in an information object. All information objects have level, code, and timestamp properties. Some information objects have a data property (containing return data, often in an object or array) and description and details properties, which typically provide information about errors.

Create your first Flash application

This section contains the code for a simple Flash application that calls the getAppStats() method.

To call Administration APIs over RTMP, you need a Flash Player or AIR client. The following sample is built in Flash.

Note:

You can call Administration APIs from applications written in ActionScript 1.0, ActionScript 2.0, or ActionScript 3.0.

  1. In Flash, create an application with the following elements:

    • An input text field named appName

    • A button called button_btn

    • A multiline, dynamic text field called outputBox

    • A scroll component attached to the outputBox text field

    Note:

    Because this is a Adobe Media Server application, you must create an application directory with the application name in the RootInstall\applications directory.

  2. Enter the following code on frame 1 of a Flash file:

     /** Establishes the connection to Adobe Media Server **/ 
      
     ncAdmin = new NetConnection(); 
     // Replace admin_name and admin_pass with your 
     // administrator name and password. 
     ncAdmin.connect("rtmp://localhost:1111/admin","admin_name","admin_pass"); 
      
     /** Makes the API call, for example, "getAppStats" **/ 
     function doGetAppStats() { 
         function onGetAppStats(){ 
             this.onResult = function(info){ 
                 if (info.code != "NetConnection.Call.Success"){ 
                     outputBox.text = "Call failed: " + info.description; 
                 } else { 
                     outputBox.text = "Info for "+appName.text+ " returned:" + newline; 
                     printObj(info, outputBox); 
                 } 
             }; 
         } 
         // Calls the getAppStats() API on the name of application 
         // in the input text field 
         // places the response in the onGetAppStats funtion 
         ncAdmin.call("getAppStats", new onGetAppStats(), appName.text); 
     } 
      
     function printObj(obj, destination){ 
         for (var prop in obj) { 
             destination.text += "\t"; 
             destination.text += prop + " = " + obj[prop] + newline; 
             if (typeof (obj[prop]) == "object") { // recursively call printObj 
                 printObj(obj[prop], destination); 
             } 
         } 
     } 
      
     button_btn.onRelease = function(){ 
         doGetAppStats(); 
     }
  3. Before running this sample application, start another Adobe Media Server application.

  4. Open the Administration Console to verify that the application you started in step 3 is running.

  5. Run the sample Flash application and enter the name of the application you started in step 3 in the input text field.

This example uses the NetConnection class to make a single request to the Adobe Media Server. If you want to create a persistent connection that updates automatically (like the Administration Console), you can use the NetStream class to create a streaming connection over the NetConnection.

Create your first application in Flex

The following application built in Flex uses the HTTPService class to call the Adobe Media Server administration API. It calls the getAppStats method and prints the results to the TextArea control.

Before you compile and run this example, you must add your admin username and password to the request parameters.

When you run the example, enter an application name in the TextInput control and click the Get App Stats button. Default applications include “live” and “vod”, but you can use the name of any application that you created on the server.

<?xml version="1.0" encoding="utf-8"?> 
<s:Application  
        xmlns:s="library://ns.adobe.com/flex/spark" 
        > 
    <fx:Declarations> 
        <s:HTTPService id="myService" 
            url="http://localhost:1111/admin/getAppStats" 
            method="GET" 
            resultFormat="e4x" 
            result="myServiceResultHandler()">             
            <s:request xmlns=""> 
                <!-- Replace these with your admin username and password. --> 
                <auser>your_admin_username</auser> 
                <apswd>your_admin_password</apswd> 
            </s:request> 
        </s:HTTPService> 
    </fx:Declarations> 
    <fx:Script> 
        <![CDATA[ 
            private function myServiceResultHandler():void { 
                outputBox.text = myService.lastResult.toString(); 
            } 
            private function doButtonClick():void { 
                /* Add the appName parameter to the request. */ 
                /* Examples include "vod" and "live". */ 
                myService.request.appName = appName.text; 
                myService.send(); 
            } 
        ]]> 
    </fx:Script> 
    <s:layout> 
        <s:VerticalLayout paddingTop="10" paddingLeft="10"/> 
    </s:layout> 
    <s:Label text="Enter an app name (e.g., live or vod):" 
        fontSize="14" 
        fontWeight="bold"/> 
    <s:HGroup> 
        <s:TextInput id="appName" width="259"/> 
        <s:Button id="button_btn" label="Get App Stats" click="doButtonClick()"/>         
    </s:HGroup> 
    <s:Label text="App Stats:" fontSize="14" fontWeight="bold"/> 
    <s:TextArea id="outputBox" height="800" width="359"/> 
</s:Application>

This application was written for Flex 4.

If the call is successful, the getAppStats method returns a result similar to the following:<result> <level>status</level> <code>NetConnection.Call.Success</code> <timestamp>6/30/2010 2:42:21 PM</timestamp> <data> <launch_time>6/30/2010 2:42:03 PM</launch_time> <up_time>17</up_time> <bw_in>17060</bw_in> <bw_out>17501</bw_out> <bytes_in>290075</bytes_in> <bytes_out>271130</bytes_out> <msg_in>202</msg_in> <msg_out>61</msg_out> <msg_dropped>0</msg_dropped> <total_connects>2</total_connects> <total_disconnects>0</total_disconnects> <connected>2</connected> <normal_connects>2</normal_connects> <virtual_connects>0</virtual_connects> <group_connects>0</group_connects> <service_connects>0</service_connects> <service_requests>0</service_requests> <admin_connects>0</admin_connects> <accepted>2</accepted> <rejected>0</rejected> <total_instances_loaded>1</total_instances_loaded> <total_instances_unloaded>0</total_instances_unloaded> <swf_verification_attempts>0</swf_verification_attempts> <swf_verification_exceptions>0</swf_verification_exceptions> <swf_verification_failures>0</swf_verification_failures> <swf_verification_unsupported_rejects>0</swf_verification_unsupported_rejects> <swf_verification_matches>0</swf_verification_matches> <swf_verification_remote_misses>0</swf_verification_remote_misses> <cores> <_0> <pid>15720</pid> <core_id>0</core_id> </_0> </cores> <server_bytes_in>0</server_bytes_in> <server_bytes_out>0</server_bytes_out> </data> </result>

 

<result> 
    <level>status</level> 
    <code>NetConnection.Call.Success</code> 
    <timestamp>6/30/2010 2:42:21 PM</timestamp> 
    <data> 
        <launch_time>6/30/2010 2:42:03 PM</launch_time> 
        <up_time>17</up_time> 
        <bw_in>17060</bw_in> 
        <bw_out>17501</bw_out> 
        <bytes_in>290075</bytes_in> 
        <bytes_out>271130</bytes_out> 
        <msg_in>202</msg_in> 
        <msg_out>61</msg_out> 
        <msg_dropped>0</msg_dropped> 
        <total_connects>2</total_connects> 
        <total_disconnects>0</total_disconnects> 
        <connected>2</connected> 
        <normal_connects>2</normal_connects> 
        <virtual_connects>0</virtual_connects> 
        <group_connects>0</group_connects> 
        <service_connects>0</service_connects> 
        <service_requests>0</service_requests> 
        <admin_connects>0</admin_connects> 
        <accepted>2</accepted> 
        <rejected>0</rejected> 
        <total_instances_loaded>1</total_instances_loaded> 
        <total_instances_unloaded>0</total_instances_unloaded> 
        <swf_verification_attempts>0</swf_verification_attempts> 
        <swf_verification_exceptions>0</swf_verification_exceptions> 
        <swf_verification_failures>0</swf_verification_failures> 
        <swf_verification_unsupported_rejects>0</swf_verification_unsupported_rejects> 
        <swf_verification_matches>0</swf_verification_matches> 
        <swf_verification_remote_misses>0</swf_verification_remote_misses> 
        <cores> 
            <_0> 
                <pid>15720</pid> 
                <core_id>0</core_id> 
            </_0> 
        </cores> 
        <server_bytes_in>0</server_bytes_in> 
        <server_bytes_out>0</server_bytes_out> 
    </data> 
</result>

This work is licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License  Twitter™ and Facebook posts are not covered under the terms of Creative Commons.

Legal Notices   |   Online Privacy Policy