<?xml version="1.0" encoding="UTF-8"?> <chapter xml:id="api.commands" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude" version="5.0" > <title> Commands : Execute Perforce commands </title> <para> The Perforce Web API lets you access Perforce commands via the run methods, that basically operate like the <literal>p4</literal> command line client. The main exception is that you do not have a client workspace, so several methods are not allowed. (See the section <link linkend="api.commands.not_allowed">Perforce commands not allowed</link> later in this chapter. </para> <informaltable> <tgroup cols="2"> <colspec colname="topic" colwidth="*" /> <colspec colname="description" colwidth="*" /> <thead> <row> <entry><para>Path</para></entry> <entry><para>Description</para></entry> </row> </thead> <tbody> <row> <entry><para><link linkend="api.commands.v1_run_GET"> <literal>GET /v1/commands/[command]</literal></link></para></entry> <entry><para>Executes a generic Perforce command with no input data.</para></entry> </row> <row> <entry><para><link linkend="api.commands.v1_run_POST"> <literal>POST /v1/commands/[command]</literal></link></para></entry> <entry><para>Executes a generic Perforce command with input data.</para></entry> </row> </tbody> </tgroup> </informaltable> <para> For more information regarding what commands are available, please review the latest documentation at: <ulink url="http://www.perforce.com/perforce/doc.current/manuals/cmdref/" /> </para> <simplesect xml:id="api.commands.not_allowed"> <title> Perforce commands not allowed </title> <itemizedlist> <listitem><para>add</para></listitem> <listitem><para>change</para></listitem> <listitem><para>changelist</para></listitem> <listitem><para>clean</para></listitem> <listitem><para>copy</para></listitem> <listitem><para>cstat</para></listitem> <listitem><para>delete</para></listitem> <listitem><para>diff</para></listitem> <listitem><para>edit</para></listitem> <listitem><para>flush</para></listitem> <listitem><para>have</para></listitem> <listitem><para>integ</para></listitem> <listitem><para>integrate</para></listitem> <listitem><para>lock</para></listitem> <listitem><para>login</para></listitem> <listitem><para>logout</para></listitem> <listitem><para>move</para></listitem> <listitem><para>reconcile</para></listitem> <listitem><para>rename</para></listitem> <listitem><para>reopen</para></listitem> <listitem><para>resolve</para></listitem> <listitem><para>resolved</para></listitem> <listitem><para>revert</para></listitem> <listitem><para>shelve</para></listitem> <listitem><para>submit</para></listitem> <listitem><para>sync</para></listitem> <listitem><para>unlock</para></listitem> <listitem><para>unshelve</para></listitem> <listitem><para>where</para></listitem> </itemizedlist> </simplesect> <section xml:id="api.commands.v1_run_GET"> <title><literal>GET /v1/commands/[command]</literal></title> <para> Executes a generic Perforce command with no input data. </para> <para> Some experimentation will be required for you to determine exactly what the input and output of data will be. The exact data structure will depend upon what command was run. Commands are subject to the same restrictions of other API clients; if you require admin access with the <literal>p4</literal> client, the authenticated user on this request will also require admin access. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.commands.v1_run_GET.parameters"> <title>Parameters</title> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry> <literal>cmd</literal> </entry> <entry> The Perforce command to run. Should not be in the list <link linkend="api.commands.not_allowed">Perforce commands not allowed</link>. </entry> <entry> <literal>string</literal> </entry> <entry> <literal>path parameter</literal> </entry> <entry> <literal>Yes</literal> </entry> </row> <row> <entry> <literal>argN</literal> </entry> <entry> (N is a number, e.g., <literal>arg0, arg1, etc</literal>.) Specify multiple <literal>argN</literal> values for each argument to pass on. </entry> <entry> <literal>string</literal> </entry> <entry> <literal>query parameter</literal> </entry> <entry> <literal>No</literal> </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.commands.v1_run_GET.example"> <title>JSON Example</title> <para> Here we'll use the equivalent of the command <literal>p4 user -o jdoe</literal>. </para> <programlisting> GET /v1/commands/user?arg0=-o&arg1=jdoe HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj</programlisting> <para> Our response is: </para> <programlisting language="json"> HTTP/1.1 200 OK ContentType: application/json [{ "User": "jdoe", "Type": "standard", "Email": "jdoe@example.com", "Update": "2014/09/11 13:53:01", "Access": "2014/09/16 12:25:38", "FullName": "John Doe", "Password": "******", "passwordChange": "2014/09/11 13:53:01" }]</programlisting> <para>(The JSON output above has been formatted.)</para> <para>Note how most return values will by default return a list from the <literal>/v1/command/[command]</literal> method. Also, you may encounter additional or unexpected fields.</para> </simplesect> </section> <section xml:id="api.commands.v1_run_POST"> <title><literal>POST /v1/commands/[command]</literal></title> <para> Executes a generic Perforce command with input data. </para> <para> The typical use case here is likely covered by one of the other spec management, methods, e.g., <literal>/v1/users</literal>. This method is provided in case your server responds to additional spec types not covered elsewhere. </para> <para> This method requires authentication. See <link linkend="clientprog.authentication">Perforce Web API Authentication</link> </para> <simplesect xml:id="api.commands.v1_run_POST.parameters"> <title>Parameters</title> <para> This method will accept a JSON body that meets the expected input of your command. </para> <informaltable> <tgroup cols="5"> <colspec colname="parameter" colwidth="*"/> <colspec colname="description" colwidth="4*"/> <colspec colname="type" colwidth="*"/> <colspec colname="paramtype" colwidth="*"/> <colspec colname="required" colwidth="*"/> <thead> <row> <entry> <para>Parameter</para> </entry> <entry> <para>Description</para> </entry> <entry> <para>Type</para> </entry> <entry> <para>Parameter Type</para> </entry> <entry> <para>Required</para> </entry> </row> </thead> <tbody> <row> <entry> <literal>cmd</literal> </entry> <entry> The Perforce command to run. Should not be in the list <link linkend="api.commands.not_allowed">Perforce commands not allowed</link>. </entry> <entry> <literal>string</literal> </entry> <entry> <literal>path parameter</literal> </entry> <entry> <literal>Yes</literal> </entry> </row> <row> <entry> <literal>argN</literal> </entry> <entry> (N is a number, e.g., <literal>arg0, arg1, etc</literal>.) Specify multiple <literal>argN</literal> values for each argument to pass on. </entry> <entry> <literal>string</literal> </entry> <entry> <literal>query parameter</literal> </entry> <entry> <literal>No</literal> </entry> </row> </tbody> </tgroup> </informaltable> </simplesect> <simplesect xml:id="api.commands.v1_run_POST.response"> <title>Response</title> <para> The response of each command depends upon the command run. In general, you are likely going to get tagged server responses that appear like errors, but with <literal>MessageSeverity</literal> levels of 1 (informative) or 2 (warning). We do not consider these errors, but the output may be helpful to your application code. </para> </simplesect> <simplesect xml:id="api.commands.v1_run_POST.example"> <title>JSON Example</title> <para> Here we'll use the equivalent of the command <literal>p4 user -i -f</literal>, where the body creates a new user </para> <programlisting> POST /v1/commands/user?arg0=-i&arg1=-f HTTP/1.1 Authorization: Basic c3VwZXI6NzcxMmJkMTAtOGQxMi00ZmUwLTgxM2MtZmM2OTExODQ3Yjdj { "User": "newuser", "FullName": "A New User", "Email": "newuser@example.com" }</programlisting> <para> Our response may contain tagged server output usable for error checking: </para> <programlisting language="json"> HTTP/1.1 200 OK ContentType: application/json [{ "MessageCode":6500, "MessageSeverity":1, "MessageText":"User newuser saved." }]</programlisting> <para>(The JSON output above has been formatted.)</para> <para>Note how most return values will by default return a list from the <literal>/v1/commands/[command]</literal> method. Also, you may see fields that resemble errors, but use an 'info' level of severity (1). Any real error response will generally have a severity of 3 or 4.</para> </simplesect> </section> </chapter>
# | Change | User | Description | Committed | |
---|---|---|---|---|---|
#2 | 13972 | tjuricek |
Removing old microservice implementations. The system is now mostly a monolith. Eventually there will be a websocket service. |
||
#1 | 13458 | tjuricek |
Revising P4 Web API docbook documentation to become the Perforce Web Services guide. Right now this is just focused on the Qt SDK. The remaining protocol documentation, etc, will happen eventually. |
||
//guest/perforce_software/helix-web-services/main/p4_web_api/p4_web_api/docbook/xml/methods/commands.xml | |||||
#1 | 13412 | tjuricek |
Initial version of the web-services mainline. This is a collection of several projects, that will likely often get released together, though many of them may not always be relevant. See the README for more information. |