|
1 <?php |
|
2 /** |
|
3 * Zend Framework |
|
4 * |
|
5 * LICENSE |
|
6 * |
|
7 * This source file is subject to the new BSD license that is bundled |
|
8 * with this package in the file LICENSE.txt. |
|
9 * It is also available through the world-wide-web at this URL: |
|
10 * http://framework.zend.com/license/new-bsd |
|
11 * If you did not receive a copy of the license and are unable to |
|
12 * obtain it through the world-wide-web, please send an email |
|
13 * to license@zend.com so we can send you a copy immediately. |
|
14 * |
|
15 * @category Zend |
|
16 * @package Zend_Service_Amazon |
|
17 * @subpackage Ec2 |
|
18 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) |
|
19 * @license http://framework.zend.com/license/new-bsd New BSD License |
|
20 * @version $Id: Image.php 20096 2010-01-06 02:05:09Z bkarwin $ |
|
21 */ |
|
22 |
|
23 /** |
|
24 * @see Zend_Service_Amazon_Ec2_Abstract |
|
25 */ |
|
26 require_once 'Zend/Service/Amazon/Ec2/Abstract.php'; |
|
27 |
|
28 /** |
|
29 * An Amazon EC2 interface to register, describe and deregister Amamzon Machine Instances (AMI) |
|
30 * |
|
31 * @category Zend |
|
32 * @package Zend_Service_Amazon |
|
33 * @subpackage Ec2 |
|
34 * @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) |
|
35 * @license http://framework.zend.com/license/new-bsd New BSD License |
|
36 */ |
|
37 class Zend_Service_Amazon_Ec2_Image extends Zend_Service_Amazon_Ec2_Abstract |
|
38 { |
|
39 /** |
|
40 * Registers an AMI with Amazon EC2. Images must be registered before |
|
41 * they can be launched. |
|
42 * |
|
43 * Each AMI is associated with an unique ID which is provided by the Amazon |
|
44 * EC2 service through the RegisterImage operation. During registration, Amazon |
|
45 * EC2 retrieves the specified image manifest from Amazon S3 and verifies that |
|
46 * the image is owned by the user registering the image. |
|
47 * |
|
48 * The image manifest is retrieved once and stored within the Amazon EC2. |
|
49 * Any modifications to an image in Amazon S3 invalidates this registration. |
|
50 * If you make changes to an image, deregister the previous image and register |
|
51 * the new image. For more information, see DeregisterImage. |
|
52 * |
|
53 * @param string $imageLocation Full path to your AMI manifest in Amazon S3 storage. |
|
54 * @return string The ami fro the newly registred image; |
|
55 */ |
|
56 public function register($imageLocation) |
|
57 { |
|
58 $params = array(); |
|
59 $params['Action'] = 'RegisterImage'; |
|
60 $params['ImageLocation']= $imageLocation; |
|
61 |
|
62 $response = $this->sendRequest($params); |
|
63 $xpath = $response->getXPath(); |
|
64 |
|
65 $amiId = $xpath->evaluate('string(//ec2:imageId/text())'); |
|
66 |
|
67 return $amiId; |
|
68 } |
|
69 |
|
70 /** |
|
71 * Returns information about AMIs, AKIs, and ARIs available to the user. |
|
72 * Information returned includes image type, product codes, architecture, |
|
73 * and kernel and RAM disk IDs. Images available to the user include public |
|
74 * images available for any user to launch, private images owned by the user |
|
75 * making the request, and private images owned by other users for which the |
|
76 * user has explicit launch permissions. |
|
77 * |
|
78 * Launch permissions fall into three categories: |
|
79 * public: The owner of the AMI granted launch permissions for the AMI |
|
80 * to the all group. All users have launch permissions for these AMIs. |
|
81 * explicit: The owner of the AMI granted launch permissions to a specific user. |
|
82 * implicit: A user has implicit launch permissions for all AMIs he or she owns. |
|
83 * |
|
84 * The list of AMIs returned can be modified by specifying AMI IDs, AMI owners, |
|
85 * or users with launch permissions. If no options are specified, Amazon EC2 returns |
|
86 * all AMIs for which the user has launch permissions. |
|
87 * |
|
88 * If you specify one or more AMI IDs, only AMIs that have the specified IDs are returned. |
|
89 * If you specify an invalid AMI ID, a fault is returned. If you specify an AMI ID for which |
|
90 * you do not have access, it will not be included in the returned results. |
|
91 * |
|
92 * If you specify one or more AMI owners, only AMIs from the specified owners and for |
|
93 * which you have access are returned. The results can include the account IDs of the |
|
94 * specified owners, amazon for AMIs owned by Amazon or self for AMIs that you own. |
|
95 * |
|
96 * If you specify a list of executable users, only users that have launch permissions |
|
97 * for the AMIs are returned. You can specify account IDs (if you own the AMI(s)), self |
|
98 * for AMIs for which you own or have explicit permissions, or all for public AMIs. |
|
99 * |
|
100 * @param string|array $imageId A list of image descriptions |
|
101 * @param string|array $owner Owners of AMIs to describe. |
|
102 * @param string|array $executableBy AMIs for which specified users have access. |
|
103 * @return array |
|
104 */ |
|
105 public function describe($imageId = null, $owner = null, $executableBy = null) |
|
106 { |
|
107 $params = array(); |
|
108 $params['Action'] = 'DescribeImages'; |
|
109 |
|
110 if(is_array($imageId) && !empty($imageId)) { |
|
111 foreach($imageId as $k=>$name) { |
|
112 $params['ImageId.' . ($k+1)] = $name; |
|
113 } |
|
114 } elseif($imageId) { |
|
115 $params['ImageId.1'] = $imageId; |
|
116 } |
|
117 |
|
118 if(is_array($owner) && !empty($owner)) { |
|
119 foreach($owner as $k=>$name) { |
|
120 $params['Owner.' . ($k+1)] = $name; |
|
121 } |
|
122 } elseif($owner) { |
|
123 $params['Owner.1'] = $owner; |
|
124 } |
|
125 |
|
126 if(is_array($executableBy) && !empty($executableBy)) { |
|
127 foreach($executableBy as $k=>$name) { |
|
128 $params['ExecutableBy.' . ($k+1)] = $name; |
|
129 } |
|
130 } elseif($executableBy) { |
|
131 $params['ExecutableBy.1'] = $executableBy; |
|
132 } |
|
133 |
|
134 $response = $this->sendRequest($params); |
|
135 |
|
136 $xpath = $response->getXPath(); |
|
137 $nodes = $xpath->query('//ec2:imagesSet/ec2:item'); |
|
138 |
|
139 $return = array(); |
|
140 foreach ($nodes as $node) { |
|
141 $item = array(); |
|
142 |
|
143 $item['imageId'] = $xpath->evaluate('string(ec2:imageId/text())', $node); |
|
144 $item['imageLocation'] = $xpath->evaluate('string(ec2:imageLocation/text())', $node); |
|
145 $item['imageState'] = $xpath->evaluate('string(ec2:imageState/text())', $node); |
|
146 $item['imageOwnerId'] = $xpath->evaluate('string(ec2:imageOwnerId/text())', $node); |
|
147 $item['isPublic'] = $xpath->evaluate('string(ec2:isPublic/text())', $node); |
|
148 $item['architecture'] = $xpath->evaluate('string(ec2:architecture/text())', $node); |
|
149 $item['imageType'] = $xpath->evaluate('string(ec2:imageType/text())', $node); |
|
150 $item['kernelId'] = $xpath->evaluate('string(ec2:kernelId/text())', $node); |
|
151 $item['ramdiskId'] = $xpath->evaluate('string(ec2:ramdiskId/text())', $node); |
|
152 $item['platform'] = $xpath->evaluate('string(ec2:platform/text())', $node); |
|
153 |
|
154 $return[] = $item; |
|
155 unset($item, $node); |
|
156 } |
|
157 |
|
158 return $return; |
|
159 } |
|
160 |
|
161 /** |
|
162 * Deregisters an AMI. Once deregistered, instances of the AMI can no longer be launched. |
|
163 * |
|
164 * @param string $imageId Unique ID of a machine image, returned by a call |
|
165 * to RegisterImage or DescribeImages. |
|
166 * @return boolean |
|
167 */ |
|
168 public function deregister($imageId) |
|
169 { |
|
170 $params = array(); |
|
171 $params['Action'] = 'DeregisterImage'; |
|
172 $params['ImageId'] = $imageId; |
|
173 |
|
174 $response = $this->sendRequest($params); |
|
175 $xpath = $response->getXPath(); |
|
176 |
|
177 $return = $xpath->evaluate('string(//ec2:return/text())'); |
|
178 |
|
179 return ($return === "true"); |
|
180 } |
|
181 |
|
182 /** |
|
183 * Modifies an attribute of an AMI. |
|
184 * |
|
185 * Valid Attributes: |
|
186 * launchPermission: Controls who has permission to launch the AMI. Launch permissions |
|
187 * can be granted to specific users by adding userIds. |
|
188 * To make the AMI public, add the all group. |
|
189 * productCodes: Associates a product code with AMIs. This allows developers to |
|
190 * charge users for using AMIs. The user must be signed up for the |
|
191 * product before they can launch the AMI. This is a write once attribute; |
|
192 * after it is set, it cannot be changed or removed. |
|
193 * |
|
194 * @param string $imageId AMI ID to modify. |
|
195 * @param string $attribute Specifies the attribute to modify. See the preceding |
|
196 * attributes table for supported attributes. |
|
197 * @param string $operationType Specifies the operation to perform on the attribute. |
|
198 * See the preceding attributes table for supported operations for attributes. |
|
199 * Valid Values: add | remove |
|
200 * Required for launchPermssion Attribute |
|
201 * |
|
202 * @param string|array $userId User IDs to add to or remove from the launchPermission attribute. |
|
203 * Required for launchPermssion Attribute |
|
204 * @param string|array $userGroup User groups to add to or remove from the launchPermission attribute. |
|
205 * Currently, the all group is available, which will make it a public AMI. |
|
206 * Required for launchPermssion Attribute |
|
207 * @param string $productCode Attaches a product code to the AMI. Currently only one product code |
|
208 * can be associated with an AMI. Once set, the product code cannot be changed or reset. |
|
209 * Required for productCodes Attribute |
|
210 * @return boolean |
|
211 */ |
|
212 public function modifyAttribute($imageId, $attribute, $operationType = 'add', $userId = null, $userGroup = null, $productCode = null) |
|
213 { |
|
214 $params = array(); |
|
215 $params['Action'] = 'ModifyImageAttribute'; |
|
216 $parmas['ImageId'] = $imageId; |
|
217 $params['Attribute'] = $attribute; |
|
218 |
|
219 switch($attribute) { |
|
220 case 'launchPermission': |
|
221 // break left out |
|
222 case 'launchpermission': |
|
223 $params['Attribute'] = 'launchPermission'; |
|
224 $params['OperationType'] = $operationType; |
|
225 |
|
226 if(is_array($userId) && !empty($userId)) { |
|
227 foreach($userId as $k=>$name) { |
|
228 $params['UserId.' . ($k+1)] = $name; |
|
229 } |
|
230 } elseif($userId) { |
|
231 $params['UserId.1'] = $userId; |
|
232 } |
|
233 |
|
234 if(is_array($userGroup) && !empty($userGroup)) { |
|
235 foreach($userGroup as $k=>$name) { |
|
236 $params['UserGroup.' . ($k+1)] = $name; |
|
237 } |
|
238 } elseif($userGroup) { |
|
239 $params['UserGroup.1'] = $userGroup; |
|
240 } |
|
241 |
|
242 break; |
|
243 case 'productCodes': |
|
244 // break left out |
|
245 case 'productcodes': |
|
246 $params['Attribute'] = 'productCodes'; |
|
247 $params['ProductCode.1'] = $productCode; |
|
248 break; |
|
249 default: |
|
250 require_once 'Zend/Service/Amazon/Ec2/Exception.php'; |
|
251 throw new Zend_Service_Amazon_Ec2_Exception('Invalid Attribute Passed In. Valid Image Attributes are launchPermission and productCode.'); |
|
252 break; |
|
253 } |
|
254 |
|
255 $response = $this->sendRequest($params); |
|
256 $xpath = $response->getXPath(); |
|
257 |
|
258 $return = $xpath->evaluate('string(//ec2:return/text())'); |
|
259 |
|
260 return ($return === "true"); |
|
261 } |
|
262 |
|
263 /** |
|
264 * Returns information about an attribute of an AMI. Only one attribute can be specified per call. |
|
265 * |
|
266 * @param string $imageId ID of the AMI for which an attribute will be described. |
|
267 * @param string $attribute Specifies the attribute to describe. Valid Attributes are |
|
268 * launchPermission, productCodes |
|
269 */ |
|
270 public function describeAttribute($imageId, $attribute) |
|
271 { |
|
272 $params = array(); |
|
273 $params['Action'] = 'DescribeImageAttribute'; |
|
274 $params['ImageId'] = $imageId; |
|
275 $params['Attribute'] = $attribute; |
|
276 |
|
277 $response = $this->sendRequest($params); |
|
278 $xpath = $response->getXPath(); |
|
279 |
|
280 $return = array(); |
|
281 $return['imageId'] = $xpath->evaluate('string(//ec2:imageId/text())'); |
|
282 |
|
283 // check for launchPermission |
|
284 if($attribute == 'launchPermission') { |
|
285 $lPnodes = $xpath->query('//ec2:launchPermission/ec2:item'); |
|
286 |
|
287 if($lPnodes->length > 0) { |
|
288 $return['launchPermission'] = array(); |
|
289 foreach($lPnodes as $node) { |
|
290 $return['launchPermission'][] = $xpath->evaluate('string(ec2:userId/text())', $node); |
|
291 } |
|
292 } |
|
293 } |
|
294 |
|
295 // check for product codes |
|
296 if($attribute == 'productCodes') { |
|
297 $pCnodes = $xpath->query('//ec2:productCodes/ec2:item'); |
|
298 if($pCnodes->length > 0) { |
|
299 $return['productCodes'] = array(); |
|
300 foreach($pCnodes as $node) { |
|
301 $return['productCodes'][] = $xpath->evaluate('string(ec2:productCode/text())', $node); |
|
302 } |
|
303 } |
|
304 } |
|
305 |
|
306 return $return; |
|
307 |
|
308 } |
|
309 |
|
310 /** |
|
311 * Resets an attribute of an AMI to its default value. The productCodes attribute cannot be reset |
|
312 * |
|
313 * @param string $imageId ID of the AMI for which an attribute will be reset. |
|
314 * @param String $attribute Specifies the attribute to reset. Currently, only launchPermission is supported. |
|
315 * In the case of launchPermission, all public and explicit launch permissions for |
|
316 * the AMI are revoked. |
|
317 * @return boolean |
|
318 */ |
|
319 public function resetAttribute($imageId, $attribute) |
|
320 { |
|
321 $params = array(); |
|
322 $params['Action'] = 'ResetImageAttribute'; |
|
323 $params['ImageId'] = $imageId; |
|
324 $params['Attribute'] = $attribute; |
|
325 |
|
326 $response = $this->sendRequest($params); |
|
327 $xpath = $response->getXPath(); |
|
328 |
|
329 $return = $xpath->evaluate('string(//ec2:return/text())'); |
|
330 |
|
331 return ($return === "true"); |
|
332 } |
|
333 } |