Skip to content
This repository
Newer
Older
100644 434 lines (342 sloc) 14.424 kb
ff90b2cd »
2014-01-10 address PR feedback
1 # Windows Azure SDK for Node.js
085ef846 »
2013-10-16 Update README.md
2
fbb75a6e »
2014-04-08 Update README.md
3 [![NPM version](https://badge.fury.io/js/azure.png)](http://badge.fury.io/js/azure) [![Build Status](https://travis-ci.org/Azure/azure-sdk-for-node.png?branch=master)](https://travis-ci.org/Azure/azure-sdk-for-node)
ef2332d8 »
2012-02-23 Migrated README.md to markdown
4
ff90b2cd »
2014-01-10 address PR feedback
5 This project provides a Node.js package that makes it easy to consume and manage Windows Azure Services.
6
7 # Features
8
9 * Storage
10 * Blob
11 * Table
12 * Storage Queue
ef2332d8 »
2012-02-23 Migrated README.md to markdown
13 * Service Bus
ff90b2cd »
2014-01-10 address PR feedback
14 * Queue
15 * Topic
16 * Notification Hub
8ff8ff6d »
2012-04-21 Updating README.md
17 * Service Runtime
ff90b2cd »
2014-01-10 address PR feedback
18 * [Core management](https://github.com/WindowsAzure/azure-sdk-for-node/blob/master/lib/services/management/README.md)
19 * [Compute management](https://github.com/WindowsAzure/azure-sdk-for-node/blob/master/lib/services/computeManagement/README.md)
20 * Virtual Machine
21 * Cloud Service
22 * [Web Site management](https://github.com/WindowsAzure/azure-sdk-for-node/blob/master/lib/services/webSiteManagement/README.md)
23 * [Virtual Network managment](https://github.com/WindowsAzure/azure-sdk-for-node/blob/dev/lib/services/networkManagement/README.md)
24 * [Storage Account management](https://github.com/WindowsAzure/azure-sdk-for-node/blob/master/lib/services/storageManagement/README.md)
25 * [SQL Database management](https://github.com/WindowsAzure/azure-sdk-for-node/blob/master/lib/services/sqlManagement/README.md)
26 * [Service Bus management](https://github.com/WindowsAzure/azure-sdk-for-node/blob/master/lib/services/serviceBusManagement/README.md)
27 * HDInsight management
8ff8ff6d »
2012-04-21 Updating README.md
28
ef2332d8 »
2012-02-23 Migrated README.md to markdown
29 # Getting Started
30
ff90b2cd »
2014-01-10 address PR feedback
31 ## Install from npm
32
33 We provide both fine-grained modules for different Windows Azure services which you can install separately, and an all-up module which contains everything.
74730969 »
2012-02-23 Migrated README.md to markdown
34
ff90b2cd »
2014-01-10 address PR feedback
35 **Notice**: we haven't provided fine-grained modules for every supported Windows Azure services yet. This will come soon.
ef2332d8 »
2012-02-23 Migrated README.md to markdown
36
ff90b2cd »
2014-01-10 address PR feedback
37 ### Install the all-up module
ef2332d8 »
2012-02-23 Migrated README.md to markdown
38
ff90b2cd »
2014-01-10 address PR feedback
39 ```
40 npm install azure
41 ```
ef2332d8 »
2012-02-23 Migrated README.md to markdown
42
ff90b2cd »
2014-01-10 address PR feedback
43 ### Install the fine-grained modules
ef2332d8 »
2012-02-23 Migrated README.md to markdown
44
ff90b2cd »
2014-01-10 address PR feedback
45 * Core management: ``npm install azure-mgmt``
46 * Compute management: ``npm install azure-mgmt-compute``
47 * Web Site management: ``npm install azure-mgmt-website``
48 * Virtual Network managment: ``npm install azure-mgmt-vnet``
49 * Storage Account management: ``npm install azure-mgmt-storage``
50 * SQL Database management: ``npm install azure-mgmt-sql``
51 * Service Bus management: ``npm install azure-mgmt-sb``
ef2332d8 »
2012-02-23 Migrated README.md to markdown
52
ff90b2cd »
2014-01-10 address PR feedback
53 ## Usage
ef2332d8 »
2012-02-23 Migrated README.md to markdown
54
ff90b2cd »
2014-01-10 address PR feedback
55 ### Table Storage
ef2332d8 »
2012-02-23 Migrated README.md to markdown
56
57 To ensure a table exists, call **createTableIfNotExists**:
58
59 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
60 var tableService = azure.createTableService();
61 tableService.createTableIfNotExists('tasktable', function(error){
62 if(!error){
63 // Table exists
64 }
65 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
66 ```
67 A new entity can be added by calling **insertEntity**:
68
69 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
70 var tableService = azure.createTableService(),
71 task1 = {
72 PartitionKey : 'tasksSeattle',
73 RowKey: '1',
74 Description: 'Take out the trash',
ff90b2cd »
2014-01-10 address PR feedback
75 DueDate: new Date(2011, 12, 14, 12)
94ce5494 »
2011-12-09 0.5.0 release.
76 };
ff90b2cd »
2014-01-10 address PR feedback
77 tableService.insertEntity('tasktable', task1, function(error){
94ce5494 »
2011-12-09 0.5.0 release.
78 if(!error){
79 // Entity inserted
80 }
81 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
82 ```
83
84 The method **queryEntity** can then be used to fetch the entity that was just inserted:
85
86 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
87 var tableService = azure.createTableService();
88 tableService.queryEntity('tasktable', 'tasksSeattle', '1', function(error, serverEntity){
89 if(!error){
90 // Entity available in serverEntity variable
91 }
92 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
93 ```
94
95 ## Blob Storage
96
ff90b2cd »
2014-01-10 address PR feedback
97 The **createContainerIfNotExists** method can be used to create a
ef2332d8 »
2012-02-23 Migrated README.md to markdown
98 container in which to store a blob:
99
100 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
101 var blobService = azure.createBlobService();
102 blobService.createContainerIfNotExists('taskcontainer', {publicAccessLevel : 'blob'}, function(error){
103 if(!error){
104 // Container exists and is public
105 }
106 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
107 ```
108
2b04a143 »
2013-11-03 Update readme.md
109 To upload a file (assuming it is called task1-upload.txt and it is placed in the same folder as the script below), the method **createBlob** can be used. This method will return a writable stream which can be writen to, for instance, through piping:
ef2332d8 »
2012-02-23 Migrated README.md to markdown
110
111 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
112 var blobService = azure.createBlobService();
2b04a143 »
2013-11-03 Update readme.md
113
114 fs.createReadStream('task1-upload.txt').pipe(blobService.createBlob('taskcontainer', 'task1', azure.Constants.BlobConstants.BlobTypes.BLOCK));
ef2332d8 »
2012-02-23 Migrated README.md to markdown
115 ```
116
2b04a143 »
2013-11-03 Update readme.md
117 To download the blob and write it to the file system, a similar **getBlob** method can be used:
ef2332d8 »
2012-02-23 Migrated README.md to markdown
118
119 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
120 var blobService = azure.createBlobService();
2b04a143 »
2013-11-03 Update readme.md
121
122 blobService.getBlob('taskcontainer', 'task1').pipe(fs.createWriteStream('task1-download.txt'));
ef2332d8 »
2012-02-23 Migrated README.md to markdown
123 ```
124
4de69845 »
2013-03-20 #647: correct readme.md
125 To create a SAS URL you can use the **getBlobUrl** method. Additionally you can use the **date** helper functions to easily create a SAS that expires at some point relative to the current time.
2b047410 »
2013-02-11 updating readme
126
127 ```Javascript
128 var blobService = azure.createBlobService();
129
130 //create a SAS that expires in an hour
ff90b2cd »
2014-01-10 address PR feedback
131 var sharedAccessPolicy = {
2b047410 »
2013-02-11 updating readme
132 AccessPolicy: {
133 Expiry: azure.date.minutesFromNow(60);
134 }
135 };
136
4de69845 »
2013-03-20 #647: correct readme.md
137 var sasUrl = blobService.getBlobUrl(containerName, blobName, sharedAccessPolicy);
86619909 »
2013-02-11 Update README.md
138 ```
2b047410 »
2013-02-11 updating readme
139
ef2332d8 »
2012-02-23 Migrated README.md to markdown
140 ## Storage Queues
141
142 The **createQueueIfNotExists** method can be used to ensure a queue exists:
143
144 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
145 var queueService = azure.createQueueService();
146 queueService.createQueueIfNotExists('taskqueue', function(error){
147 if(!error){
148 // Queue exists
149 }
150 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
151 ```
152
153 The **createMessage** method can then be called to insert the message into the queue:
154
155 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
156 var queueService = azure.createQueueService();
0a1afcc6 »
2013-04-27 replacing " by '
157 queueService.createMessage('taskqueue', 'Hello world!', function(error){
94ce5494 »
2011-12-09 0.5.0 release.
158 if(!error){
159 // Message inserted
160 }
161 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
162 ```
163
6a4c9659 »
2014-01-27 simple typo fix in the the doco. getMessage to getMessages
164 It is then possible to call the **getMessages** method, process the message and then call **deleteMessage** inside the callback. This two-step process ensures messages don't get lost when they are removed from the queue.
ef2332d8 »
2012-02-23 Migrated README.md to markdown
165
166 ```Javascript
94ce5494 »
2011-12-09 0.5.0 release.
167 var queueService = azure.createQueueService(),
168 queueName = 'taskqueue';
169 queueService.getMessages(queueName, function(error, serverMessages){
170 if(!error){
171 // Process the message in less than 30 seconds, the message
ff90b2cd »
2014-01-10 address PR feedback
172 // text is available in serverMessages[0].messagetext
94ce5494 »
2011-12-09 0.5.0 release.
173
174 queueService.deleteMessage(queueName, serverMessages[0].messageid, serverMessages[0].popreceipt, function(error){
175 if(!error){
176 // Message deleted
177 }
178 });
179 }
180 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
181 ```
182
8ff8ff6d »
2012-04-21 Updating README.md
183 ## Service Bus Queues
ef2332d8 »
2012-02-23 Migrated README.md to markdown
184
8ff8ff6d »
2012-04-21 Updating README.md
185 Service Bus Queues are an alternative to Storage Queues that might be useful in scenarios where more advanced messaging features are needed (larger message sizes, message ordering, single-operaiton destructive reads, scheduled delivery) using push-style delivery (using long polling).
ef2332d8 »
2012-02-23 Migrated README.md to markdown
186
187 The **createQueueIfNotExists** method can be used to ensure a queue exists:
188
189 ```Javascript
c4031f9f »
2012-02-13 Updating README.md with ServiceBus content
190 var serviceBusService = azure.createServiceBusService();
191 serviceBusService.createQueueIfNotExists('taskqueue', function(error){
192 if(!error){
193 // Queue exists
194 }
195 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
196 ```
197
198 The **sendQueueMessage** method can then be called to insert the message into the queue:
199
200 ```Javascript
c4031f9f »
2012-02-13 Updating README.md with ServiceBus content
201 var serviceBusService = azure.createServiceBusService();
202 serviceBusService.sendQueueMessage('taskqueue', 'Hello world!', function(
203 if(!error){
204 // Message sent
205 }
206 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
207 ```
208
209 It is then possible to call the **receiveQueueMessage** method to dequeue the message.
210
211 ```Javascript
c4031f9f »
2012-02-13 Updating README.md with ServiceBus content
212 var serviceBusService = azure.createServiceBusService();
213 serviceBusService.receiveQueueMessage('taskqueue', function(error, serverMessage){
214 if(!error){
215 // Process the message
216 }
217 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
218 ```
219
8ff8ff6d »
2012-04-21 Updating README.md
220 ## Service Bus Topics
ef2332d8 »
2012-02-23 Migrated README.md to markdown
221
8ff8ff6d »
2012-04-21 Updating README.md
222 Service Bus topics are an abstraction on top of Service Bus Queues that make pub/sub scenarios easy to implement.
ef2332d8 »
2012-02-23 Migrated README.md to markdown
223
224 The **createTopicIfNotExists** method can be used to create a server-side topic:
225
226 ```Javascript
c4031f9f »
2012-02-13 Updating README.md with ServiceBus content
227 var serviceBusService = azure.createServiceBusService();
228 serviceBusService.createTopicIfNotExists('taskdiscussion', function(error){
229 if(!error){
230 // Topic exists
231 }
232 });
74730969 »
2012-02-23 Migrated README.md to markdown
233 ```
ef2332d8 »
2012-02-23 Migrated README.md to markdown
234
235 The **sendTopicMessage** method can be used to send a message to a topic:
236
237 ```Javascript
c4031f9f »
2012-02-13 Updating README.md with ServiceBus content
238 var serviceBusService = azure.createServiceBusService();
239 serviceBusService.sendTopicMessage('taskdiscussion', 'Hello world!', function(error){
240 if(!error){
241 // Message sent
242 }
243 });
ef2332d8 »
2012-02-23 Migrated README.md to markdown
244 ```
245
246 A client can then create a subscription and start consuming messages by calling the **createSubscription** method followed by the **receiveSubscriptionMessage** method. Please note that any messages sent before the subscription is created will not be received.
247
248 ```Javascript
c4031f9f »
2012-02-13 Updating README.md with ServiceBus content
249 var serviceBusService = azure.createServiceBusService(),
250 topic = 'taskdiscussion',
251 subscription = 'client1';
252
253 serviceBusService.createSubscription(topic, subscription, function(error1){
254 if(!error1){
255 // Subscription created
256
257 serviceBusService.receiveSubscriptionMessage(topic, subscription, function(error2, serverMessage){
258 if(!error2){
259 // Process message
260 }
261 });
262 }
263 });
74730969 »
2012-02-23 Migrated README.md to markdown
264 ```
e50b2622 »
2013-03-20 Document notification hubs
265
266
267 ## Notification Hubs
268
61c353ed »
2013-12-02 NotificationHubs: updated docs
269 Notification hubs allow you to send notifications to WNS, APNS, GCM, and MPNS receivers.
e50b2622 »
2013-03-20 Document notification hubs
270
39d73df5 »
2013-03-20 Applying review feedback
271 To create a notification hub, use the method **createNotificationHub**.
e50b2622 »
2013-03-20 Document notification hubs
272
273 ```JavaScript
274 var serviceBusService = azure.createServiceBusService();
275
276 serviceBusService.createNotificationHub('hubName', function (err) {
277 if (!err) {
278 // Notification hub created successfully
279 }
280 });
281 ```
282
61c353ed »
2013-12-02 NotificationHubs: updated docs
283 To send notification using native format to the notification hub use the methods of the **wns**, **apns**, **gcm**, **mpns** objects. For a full reference on WNS method templates, check http://msdn.microsoft.com/en-us/library/windows/apps/hh779725.aspx.
284 To send template (cross-platform) notifications use the send method on the **NotificationHubService** class.
e50b2622 »
2013-03-20 Document notification hubs
285
286 ```JavaScript
287 var notificationHubService = azure.createNotificationHubService('hubName');
288
61c353ed »
2013-12-02 NotificationHubs: updated docs
289 // WNS notification
e50b2622 »
2013-03-20 Document notification hubs
290 notificationHubService.wns.sendTileSquarePeekImageAndText01(
291 null,
292 {
293 image1src: 'http://foobar.com/dog.jpg',
294 image1alt: 'A dog',
295 text1: 'This is a dog',
296 text2: 'The dog is nice',
297 text3: 'The dog bites',
298 text4: 'Beware of dog'
299 },
300 function (error) {
301 if (!error) {
302 // message sent successfully
303 }
304 });
305
61c353ed »
2013-12-02 NotificationHubs: updated docs
306 // APNS notification
e50b2622 »
2013-03-20 Document notification hubs
307 notificationHubService.apns.send(
308 null,
309 {
310 alert: 'This is my toast message for iOS!',
311 expiry: expiryDate
312 },
313 function (error) {
314 if (!error) {
315 // message sent successfully
316 }
317 });
cd89e21e »
2013-06-06 updated readme for notification hubs
318
61c353ed »
2013-12-02 NotificationHubs: updated docs
319 // GCM notification
cd89e21e »
2013-06-06 updated readme for notification hubs
320 notificationHubService.gcm.send(
321 null,
322 {
323 data: { message: 'Here is a message' }
324 },
325 function (error) {
326 if (!error) {
327 //message send successfully
328 }
329 });
61c353ed »
2013-12-02 NotificationHubs: updated docs
330
331 // MPNS notification
332 notificationHubService.mpns.sendToast(
333 null,
334 {
335 text1: 'A dog',
ff90b2cd »
2014-01-10 address PR feedback
336 text2: 'This is a dog'
61c353ed »
2013-12-02 NotificationHubs: updated docs
337 },
338 function (error) {
339 if (!error) {
340 //message send successfully
341 }
342 });
343
344 // template notification
345 notificationHubService.send(
346 null,
347 {
348 message: 'This is my template notification',
ff90b2cd »
2014-01-10 address PR feedback
349 goesTo: 'all registrations irrespective of the platform'
61c353ed »
2013-12-02 NotificationHubs: updated docs
350 },
351 function (error) {
352 if (!error) {
353 //message send successfully
354 }
355 });
356
e50b2622 »
2013-03-20 Document notification hubs
357 ```
358
61c353ed »
2013-12-02 NotificationHubs: updated docs
359 To create registrations (for both native and template notifications), use the creation methods in the **wns**, **apns**, **gcm**, **mpns**. To retrieve, update and delete existing registrations, use the following methods in NotificationHubService: **getRegistration**, **listRegistrations**, **listRegistrationsByTag**, **updateRegistration**, and **deleteRegistration**.
360
e9f3ca7a »
2013-02-11 Update README.md
361 ## Service Runtime
362
363 The Service Runtime allows you to interact with the machine environment where the current role is running. Please note that these commands will only work if your code is running in a worker role inside the Azure emulator or in the cloud.
364
ff90b2cd »
2014-01-10 address PR feedback
365 The **isAvailable** method lets you determine whether the service runtime endpoint is running on the local machine. It is good practice to enclose any code that
e9f3ca7a »
2013-02-11 Update README.md
366 uses service runtime in the isAvailable callback.
367
368 ```JavaScript
369 azure.RoleEnvironment.isAvailable(function(error, available) {
370 if (available) {
371 // Place your calls to service runtime here
372 }
373 });
374 ```
375
376 The **getConfigurationSettings** method lets you obtain values from the role's .cscfg file.
377
378 ```Javascript
379 azure.RoleEnvironment.getConfigurationSettings(function(error, settings) {
380 if (!error) {
381 // You can get the value of setting "setting1" via settings['setting1']
ff90b2cd »
2014-01-10 address PR feedback
382 }
e9f3ca7a »
2013-02-11 Update README.md
383 });
384 ```
385
ff90b2cd »
2014-01-10 address PR feedback
386 The **getLocalResources** method lets you find the path to defined local storage resources for the current role. For example, the DiagnosticStore
e9f3ca7a »
2013-02-11 Update README.md
387 resource which is defined for every role provides a location for runtime diagnostics and logs.
388
389 ```Javascript
390 azure.RoleEnvironment.getLocalResources(function(error, resources) {
391 if(!error){
ff90b2cd »
2014-01-10 address PR feedback
392 // You can get the path to the role's diagnostics store via
e9f3ca7a »
2013-02-11 Update README.md
393 // resources['DiagnosticStore']['path']
394 }
395 });
396 ```
397
398 The **getCurrentRoleInstance** method lets you obtain information about endpoints defined for the current role instance:
399
400 ```JavaScript
401 azure.RoleEnvironment.getCurrentRoleInstance(function(error, instance) {
402 if (!error && instance['endpoints']) {
403 // You can get information about "endpoint1" such as its address and port via
404 // instance['endpoints']['endpoint1']['address'] and instance['endpoints']['endpoint1']['port']
405 }
406 });
407 ```
408
409 The **getRoles** method lets you obtain information about endpoints in role instances running on other machines:
410
411 ```Javascript
412 azure.RoleEnvironment.getRoles(function(error, roles) {
413 if(!error){
414 // You can get information about "instance1" of "role1" via roles['role1']['instance1']
ff90b2cd »
2014-01-10 address PR feedback
415 }
e9f3ca7a »
2013-02-11 Update README.md
416 });
417 ```
418
ef2332d8 »
2012-02-23 Migrated README.md to markdown
419 # Need Help?
420
ff90b2cd »
2014-01-10 address PR feedback
421 * [Windows Azure Forums on MSDN and Stack Overflow](http://go.microsoft.com/fwlink/?LinkId=234489)
422 * IRC channel on freenode: node-azure
94ce5494 »
2011-12-09 0.5.0 release.
423
ef2332d8 »
2012-02-23 Migrated README.md to markdown
424 # Learn More
15338341 »
2012-11-20 Applying readme and changelog changes.
425
ff90b2cd »
2014-01-10 address PR feedback
426 * [Windows Azure Node.js Developer Center](http://www.windowsazure.com/en-us/develop/nodejs/)
427 * [API reference](http://dl.windowsazure.com/nodedocs/)
428 * [Windows Azure Cross-Platform CLI](http://github.com/windowsazure/azure-sdk-tools-xplat)
15338341 »
2012-11-20 Applying readme and changelog changes.
429
ff90b2cd »
2014-01-10 address PR feedback
430 # Contribute
15338341 »
2012-11-20 Applying readme and changelog changes.
431
ff90b2cd »
2014-01-10 address PR feedback
432 * If you would like to become an active contributor to this project please follow the instructions provided in [Windows Azure Projects Contribution Guidelines](http://windowsazure.github.com/guidelines.html).
433 * If you encounter any bugs with the library please file an issue in the [Issues](https://github.com/WindowsAzure/azure-sdk-for-node/issues) section of the project.
Something went wrong with that request. Please try again.