mirror of
https://github.com/apache/cloudstack.git
synced 2025-12-19 12:03:50 +01:00
107 lines
8.9 KiB
HTML
107 lines
8.9 KiB
HTML
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>4.5. Asynchronous Commands</title><link rel="stylesheet" type="text/css" href="Common_Content/css/default.css" /><link rel="stylesheet" media="print" href="Common_Content/css/print.css" type="text/css" /><meta name="generator" content="publican 2.8" /><meta name="package" content="Apache_CloudStack-API_Developers_Guide-4.0.0-incubating-en-US-1-" /><link rel="home" href="index.html" title="CloudStack API Developer's Guide" /><link rel="up" href="api-calls.html" title="Chapter 4. Calling the CloudStack API" /><link rel="prev" href="responses.html" title="4.4. Responses" /><link rel="next" href="working-with-usage-data.html" title="Chapter 5. Working With Usage Data" /></head><body><p id="title"><a class="left" href="http://cloudstack.org"><img src="Common_Content/images/image_left.png" alt="Product Site" /></a><a class="right" href="http://docs.cloudstack.org"><img src="Common_Content/images/image_right.png" alt="Documentation Site" /></a></p><ul class="docnav"><li class="previous"><a accesskey="p" href="responses.html"><strong>Prev</strong></a></li><li class="next"><a accesskey="n" href="working-with-usage-data.html"><strong>Next</strong></a></li></ul><div xml:lang="en-US" class="section" id="asynchronous-commands" lang="en-US"><div class="titlepage"><div><div><h2 class="title" id="asynchronous-commands">4.5. Asynchronous Commands</h2></div></div></div><div class="para">
|
||
Asynchronous commands were introduced in CloudStack 2.x. Commands are designated as asynchronous when they can potentially take a long period of time to complete such as creating a snapshot or disk volume. They differ from synchronous commands by the following:
|
||
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
|
||
They are identified in the API Reference by an (A).
|
||
</div></li><li class="listitem"><div class="para">
|
||
They will immediately return a job ID to refer to the job that will be responsible in processing the command.
|
||
</div></li><li class="listitem"><div class="para">
|
||
If executed as a "create" resource command, it will return the resource ID as well as the job ID.
|
||
</div><div class="para">
|
||
You can periodically check the status of the job by making a simple API call to the command, queryAsyncJobResult and passing in the job ID.
|
||
</div></li></ul></div><div xml:lang="en-US" class="section" id="job-status" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="job-status">4.5.1. Job Status</h3></div></div></div><div class="para">
|
||
The key to using an asynchronous command is the job ID that is returned immediately once the command has been executed. With the job ID, you can periodically check the job status by making calls to queryAsyncJobResult command. The command will return three possible job status integer values:
|
||
</div><div class="itemizedlist"><ul><li class="listitem"><div class="para">
|
||
0 - Job is still in progress. Continue to periodically poll for any status changes.
|
||
</div></li><li class="listitem"><div class="para">
|
||
1 - Job has successfully completed. The job will return any successful response values associated with command that was originally executed.
|
||
</div></li><li class="listitem"><div class="para">
|
||
2 - Job has failed to complete. Please check the "jobresultcode" tag for failure reason code and "jobresult" for the failure reason.
|
||
</div></li></ul></div></div><div xml:lang="en-US" class="section" id="asynchronous-commands-example" lang="en-US"><div class="titlepage"><div><div><h3 class="title" id="asynchronous-commands-example">4.5.2. Example</h3></div></div></div><div class="para">
|
||
The following shows an example of using an asynchronous command. Assume the API command:
|
||
</div><pre class="programlisting">command=deployVirtualMachine&zoneId=1&serviceOfferingId=1&diskOfferingId=1&templateId=1
|
||
</pre><div class="para">
|
||
CloudStack will immediately return a job ID and any other additional data.
|
||
</div><pre class="programlisting">
|
||
<deployvirtualmachineresponse>
|
||
<jobid>1</jobid>
|
||
<id>100</id>
|
||
</deployvirtualmachineresponse>
|
||
</pre><div class="para">
|
||
Using the job ID, you can periodically poll for the results by using the queryAsyncJobResult command.
|
||
</div><pre class="programlisting">command=queryAsyncJobResult&jobId=1</pre><div class="para">
|
||
Three possible results could come from this query.
|
||
</div><div class="para">
|
||
Job is still pending:
|
||
</div><pre class="programlisting">
|
||
<queryasyncjobresult>
|
||
<jobid>1</jobid>
|
||
<jobstatus>0</jobstatus>
|
||
<jobprocstatus>1</jobprocstatus>
|
||
</queryasyncjobresult>
|
||
</pre><div class="para">
|
||
Job has succeeded:
|
||
</div><pre class="programlisting">
|
||
<queryasyncjobresultresponse cloud-stack-version="3.0.1.6">
|
||
<jobid>1</jobid>
|
||
<jobstatus>1</jobstatus>
|
||
<jobprocstatus>0</jobprocstatus>
|
||
<jobresultcode>0</jobresultcode>
|
||
<jobresulttype>object</jobresulttype>
|
||
<jobresult>
|
||
<virtualmachine>
|
||
<id>450</id>
|
||
<name>i-2-450-VM</name>
|
||
<displayname>i-2-450-VM</displayname>
|
||
<account>admin</account>
|
||
<domainid>1</domainid>
|
||
<domain>ROOT</domain>
|
||
<created>2011-03-10T18:20:25-0800</created>
|
||
<state>Running</state>
|
||
<haenable>false</haenable>
|
||
<zoneid>1</zoneid>
|
||
<zonename>San Jose 1</zonename>
|
||
<hostid>2</hostid>
|
||
<hostname>905-13.sjc.lab.vmops.com</hostname>
|
||
<templateid>1</templateid>
|
||
<templatename>CentOS 5.3 64bit LAMP</templatename>
|
||
<templatedisplaytext>CentOS 5.3 64bit LAMP</templatedisplaytext>
|
||
<passwordenabled>false</passwordenabled>
|
||
<serviceofferingid>1</serviceofferingid>
|
||
<serviceofferingname>Small Instance</serviceofferingname>
|
||
<cpunumber>1</cpunumber>
|
||
<cpuspeed>500</cpuspeed>
|
||
<memory>512</memory>
|
||
<guestosid>12</guestosid>
|
||
<rootdeviceid>0</rootdeviceid>
|
||
<rootdevicetype>NetworkFilesystem</rootdevicetype>
|
||
<nic>
|
||
<id>561</id>
|
||
<networkid>205</networkid>
|
||
<netmask>255.255.255.0</netmask>
|
||
<gateway>10.1.1.1</gateway>
|
||
<ipaddress>10.1.1.225</ipaddress>
|
||
<isolationuri>vlan://295</isolationuri>
|
||
<broadcasturi>vlan://295</broadcasturi>
|
||
<traffictype>Guest</traffictype>
|
||
<type>Virtual</type>
|
||
<isdefault>true</isdefault>
|
||
</nic>
|
||
<hypervisor>XenServer</hypervisor>
|
||
</virtualmachine>
|
||
</jobresult>
|
||
</queryasyncjobresultresponse>
|
||
</pre><div class="para">
|
||
Job has failed:
|
||
</div><pre class="programlisting">
|
||
<queryasyncjobresult>
|
||
<jobid>1</jobid>
|
||
<jobstatus>2</jobstatus>
|
||
<jobprocstatus>0</jobprocstatus>
|
||
<jobresultcode>551</jobresultcode>
|
||
<jobresulttype>text</jobresulttype>
|
||
<jobresult>Unable to deploy virtual machine id = 100 due to not enough capacity</jobresult>
|
||
</queryasyncjobresult>
|
||
</pre></div></div><ul class="docnav"><li class="previous"><a accesskey="p" href="responses.html"><strong>Prev</strong>4.4. Responses</a></li><li class="up"><a accesskey="u" href="#"><strong>Up</strong></a></li><li class="home"><a accesskey="h" href="index.html"><strong>Home</strong></a></li><li class="next"><a accesskey="n" href="working-with-usage-data.html"><strong>Next</strong>Chapter 5. Working With Usage Data</a></li></ul></body></html>
|