1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
|
<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.service.windowsazure.storage.blob">
<title>Zend_Service_WindowsAzure_Storage_Blob</title>
<para>
Blob Storage stores sets of binary data. Blob storage offers the following three
resources: the storage account, containers, and blobs. Within your storage account,
containers provide a way to organize sets of blobs within your storage account.
</para>
<para>
Blob Storage is offered by Windows Azure as a <acronym>REST</acronym> <acronym>API</acronym>
which is wrapped by the <classname>Zend_Service_WindowsAzure_Storage_Blob</classname> class
in order to provide a native <acronym>PHP</acronym> interface to the storage account.
</para>
<sect2 id="zend.service.windowsazure.storage.blob.api">
<title>API Examples</title>
<para>
This topic lists some examples of using the
<classname>Zend_Service_WindowsAzure_Storage_Blob</classname> class. Other features are
available in the download package, as well as a detailed <acronym>API</acronym>
documentation of those features.
</para>
<sect3 id="zend.service.windowsazure.storage.blob.api.create-container">
<title>Creating a storage container</title>
<para>
Using the following code, a blob storage container can be created on development
storage.
</para>
<example id="zend.service.windowsazure.storage.blob.api.create-container.example">
<title>Creating a storage container</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$result = $storageClient->createContainer('testcontainer');
echo 'Container name is: ' . $result->Name;
]]></programlisting>
</example>
</sect3>
<sect3 id="zend.service.windowsazure.storage.blob.api.delete-container">
<title>Deleting a storage container</title>
<para>
Using the following code, a blob storage container can be removed from development
storage.
</para>
<example id="zend.service.windowsazure.storage.blob.api.delete-container.example">
<title>Deleting a storage container</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$storageClient->deleteContainer('testcontainer');
]]></programlisting>
</example>
</sect3>
<sect3 id="zend.service.windowsazure.storage.blob.api.storing-blob">
<title>Storing a blob</title>
<para>
Using the following code, a blob can be uploaded to a blob storage container on
development storage. Note that the container has already been created before.
</para>
<example id="zend.service.windowsazure.storage.blob.api.storing-blob.example">
<title>Storing a blob</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
// upload /home/maarten/example.txt to Azure
$result = $storageClient->putBlob(
'testcontainer', 'example.txt', '/home/maarten/example.txt'
);
echo 'Blob name is: ' . $result->Name;
]]></programlisting>
</example>
</sect3>
<sect3 id="zend.service.windowsazure.storage.blob.api.copy-blob">
<title>Copying a blob</title>
<para>
Using the following code, a blob can be copied from inside the storage account. The
advantage of using this method is that the copy operation occurs in the Azure cloud
and does not involve downloading the blob. Note that the container has already been
created before.
</para>
<example id="zend.service.windowsazure.storage.blob.api.copy-blob.example">
<title>Copying a blob</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
// copy example.txt to example2.txt
$result = $storageClient->copyBlob(
'testcontainer', 'example.txt', 'testcontainer', 'example2.txt'
);
echo 'Copied blob name is: ' . $result->Name;
]]></programlisting>
</example>
</sect3>
<sect3 id="zend.service.windowsazure.storage.blob.api.download-blob">
<title>Downloading a blob</title>
<para>
Using the following code, a blob can be downloaded from a blob storage container on
development storage. Note that the container has already been created before and a
blob has been uploaded.
</para>
<example id="zend.service.windowsazure.storage.blob.api.download-blob.example">
<title>Downloading a blob</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
// download file to /home/maarten/example.txt
$storageClient->getBlob(
'testcontainer', 'example.txt', '/home/maarten/example.txt'
);
]]></programlisting>
</example>
</sect3>
<sect3 id="zend.service.windowsazure.storage.blob.api.public-blob">
<title>Making a blob publicly available</title>
<para>
By default, blob storage containers on Windows Azure are protected from public
viewing. If any user on the Internet should have access to a blob container, its ACL
can be set to public. Note that this applies to a complete container and not to a
single blob!
</para>
<para>
Using the following code, blob storage container ACL can be set on development
storage. Note that the container has already been created before.
</para>
<example id="zend.service.windowsazure.storage.blob.api.public-blob.example">
<title>Making a blob publicly available</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
// make container publicly available (enumerate all blobs and read blob data)
$storageClient->setContainerAcl('testcontainer', Zend_Service_WindowsAzure_Storage_Blob::ACL_PUBLIC_CONTAINER);
]]></programlisting>
</example>
</sect3>
</sect2>
<sect2 id="zend.service.windowsazure.storage.blob.root">
<title>Root container</title>
<para>
Windows Azure Blob Storage provides support to work with a "root container".
This means that a blob can be stored in the root of your storage account,
i.e. <filename>http://myaccount.blob.core.windows.net/somefile.txt</filename>.
</para>
<para>
In order to work with the root container, it should first be created using the
<methodname>createContainer()</methodname> method, naming the container
<varname>$root</varname>. All other operations on the root container should be issued
with the container name set to <varname>$root</varname>.
</para>
</sect2>
<sect2 id="zend.service.windowsazure.storage.blob.wrapper">
<title>Blob storage stream wrapper</title>
<para>
The Windows Azure <acronym>SDK</acronym> for <acronym>PHP</acronym> provides support
for registering a blob storage client as a <acronym>PHP</acronym> file stream wrapper.
The blob storage stream wrapper provides support for using regular file operations on
Windows Azure Blob Storage. For example, one can open a file from Windows Azure Blob
Storage with the <methodname>fopen()</methodname> function:
</para>
<example id="zend.service.windowsazure.storage.blob.wrapper.sample">
<title>Example usage of blob storage stream wrapper</title>
<programlisting language="php"><![CDATA[
$fileHandle = fopen('azure://mycontainer/myfile.txt', 'r');
// ...
fclose($fileHandle);
]]></programlisting>
</example>
<para>
In order to do this, the Windows Azure <acronym>SDK</acronym> for <acronym>PHP</acronym>
blob storage client must be registered as a stream wrapper. This can be done by calling
the <methodname>registerStreamWrapper()</methodname> method:
</para>
<example id="zend.service.windowsazure.storage.blob.wrapper.register">
<title>Registering the blob storage stream wrapper</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
// registers azure:// on this storage client
$storageClient->registerStreamWrapper();
// or:
// regiters blob:// on this storage client
$storageClient->registerStreamWrapper('blob://');
]]></programlisting>
</example>
<para>
To unregister the stream wrapper, the <methodname>unregisterStreamWrapper()</methodname>
method can be used.
</para>
</sect2>
<sect2 id="zend.service.windowsazure.storage.blob.sharedaccesssig">
<title>Shared Access Signature</title>
<para>
Windows Azure Bob Storage provides a feature called "Shared Access Signatures". By
default, there is only one level of authorization possible in Windows Azure Blob
Storage: either a container is private or it is public. Shared Access Signatures provide
a more granular method of authorization: read, write, delete and list permissions can be
assigned on a container or a blob and given to a specific client using an URL-based
model.
</para>
<para>
An example would be the following signature:
</para>
<literallayout>
http://phpstorage.blob.core.windows.net/phpazuretestshared1?st=2009-08-17T09%3A06%3A17Z&se=2009-08-17T09%3A56%3A17Z&sr=c&sp=w&sig=hscQ7Su1nqd91OfMTwTkxabhJSaspx%2BD%2Fz8UqZAgn9s%3D
</literallayout>
<para>
The above signature gives write access to the "phpazuretestshared1"
container of the "phpstorage" account.
</para>
<sect3 id="zend.service.windowsazure.storage.blob.sharedaccesssig.generate">
<title>Generating a Shared Access Signature</title>
<para>
When you are the owner of a Windows Azure Bob Storage account, you can create and
distribute a shared access key for any type of resource in your account. To do this,
the <methodname>generateSharedAccessUrl()</methodname> method of the
<classname>Zend_Service_WindowsAzure_Storage_Blob</classname> storage client can be
used.
</para>
<para>
The following example code will generate a Shared Access Signature for write access
in a container named "container1", within a timeframe of 3000 seconds.
</para>
<example id="zend.service.windowsazure.storage.blob.sharedaccesssig.generate-2">
<title>Generating a Shared Access Signature for a container</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$sharedAccessUrl = $storageClient->generateSharedAccessUrl(
'container1',
'',
'c',
'w',
$storageClient ->isoDate(time() - 500),
$storageClient ->isoDate(time() + 3000)
);
]]></programlisting>
</example>
<para>
The following example code will generate a Shared Access Signature for read access
in a blob named <filename>test.txt</filename> in a container named "container1"
within a time frame of 3000 seconds.
</para>
<example id="zend.service.windowsazure.storage.blob.sharedaccesssig-generate-3">
<title>Generating a Shared Access Signature for a blob</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob();
$sharedAccessUrl = $storageClient->generateSharedAccessUrl(
'container1',
'test.txt',
'b',
'r',
$storageClient ->isoDate(time() - 500),
$storageClient ->isoDate(time() + 3000)
);
]]></programlisting>
</example>
</sect3>
<sect3 id="zend.service.windowsazure.storage.blob.sharedaccesssig.consume">
<title>Working with Shared Access Signatures from others</title>
<para>
When you receive a Shared Access Signature from someone else, you can use the
Windows Azure <acronym>SDK</acronym> for <acronym>PHP</acronym> to work with the
addressed resource. For example, the following signature can be retrieved from the
owner of a storage account:
</para>
<literallayout>
http://phpstorage.blob.core.windows.net/phpazuretestshared1?st=2009-08-17T09%3A06%3A17Z&se=2009-08-17T09%3A56%3A17Z&sr=c&sp=w&sig=hscQ7Su1nqd91OfMTwTkxabhJSaspx%2BD%2Fz8UqZAgn9s%3D
</literallayout>
<para>
The above signature gives write access to the "phpazuretestshared1" "container" of
the phpstorage account. Since the shared key for the account is not known, the
Shared Access Signature can be used to work with the authorized resource.
</para>
<example id="zend.service.windowsazure.storage.blob.sharedaccesssig.consuming">
<title>Consuming a Shared Access Signature for a container</title>
<programlisting language="php"><![CDATA[
$storageClient = new Zend_Service_WindowsAzure_Storage_Blob(
'blob.core.windows.net', 'phpstorage', ''
);
$storageClient->setCredentials(
new Zend_Service_WindowsAzure_Credentials_SharedAccessSignature()
);
$storageClient->getCredentials()->setPermissionSet(array(
'http://phpstorage.blob.core.windows.net/phpazuretestshared1?st=2009-08-17T09%3A06%3A17Z&se=2009-08-17T09%3A56%3A17Z&sr=c&sp=w&sig=hscQ7Su1nqd91OfMTwTkxabhJSaspx%2BD%2Fz8UqZAgn9s%3D'
));
$storageClient->putBlob(
'phpazuretestshared1', 'NewBlob.txt', 'C:\Files\dataforazure.txt'
);
]]></programlisting>
</example>
<para>
Note that there was no explicit permission to write to a specific blob. Instead, the
Windows Azure <acronym>SDK</acronym> for <acronym>PHP</acronym> determined that a
permission was required to either write to that specific blob, or to write to its
container. Since only a signature was available for the latter, the Windows Azure
<acronym>SDK</acronym> for <acronym>PHP</acronym> chose those credentials to perform
the request on Windows Azure blob storage.
</para>
</sect3>
</sect2>
</sect1>
|
