Skip to content

Commit a76fbc8

Browse files
craigshoemakercraigshoemaker
committed
Restructure blob storage binding ref
1 parent 326974a commit a76fbc8

File tree

4 files changed

+1181
-1142
lines changed

4 files changed

+1181
-1142
lines changed

‎articles/azure-functions/functions-bindings-storage-blob-input.md

Lines changed: 334 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,334 @@
1+
---
2+
title: Azure Blob storage input binding for Azure Functions
3+
description: Learn how to provide Azure Blob storage data to an Azure Function.
4+
author: craigshoemaker
5+
ms.topic: reference
6+
ms.date: 02/13/2020
7+
ms.author: cshoe
8+
---
9+
10+
# Azure Blob storage input binding for Azure Functions
11+
12+
The input binding allows you to read blob storage data as input to an Azure Function.
13+
14+
## Example
15+
16+
# [C#](#tab/csharp)
17+
18+
The following example is a [C# function](functions-dotnet-class-library.md) that uses a queue trigger and an input blob binding. The queue message contains the name of the blob, and the function logs the size of the blob.
19+
20+
```csharp
21+
[FunctionName("BlobInput")]
22+
public static void Run(
23+
[QueueTrigger("myqueue-items")] string myQueueItem,
24+
[Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
25+
ILogger log)
26+
{
27+
log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
28+
}
29+
```
30+
31+
# [C# Script](#tab/csharp-script)
32+
33+
<!--Same example for input and output. -->
34+
35+
The following example shows blob input and output bindings in a *function.json* file and [C# script (.csx)](functions-reference-csharp.md) code that uses the bindings. The function makes a copy of a text blob. The function is triggered by a queue message that contains the name of the blob to copy. The new blob is named *{originalblobname}-Copy*.
36+
37+
In the *function.json* file, the `queueTrigger` metadata property is used to specify the blob name in the `path` properties:
38+
39+
```json
40+
{
41+
"bindings": [
42+
{
43+
"queueName": "myqueue-items",
44+
"connection": "MyStorageConnectionAppSetting",
45+
"name": "myQueueItem",
46+
"type": "queueTrigger",
47+
"direction": "in"
48+
},
49+
{
50+
"name": "myInputBlob",
51+
"type": "blob",
52+
"path": "samples-workitems/{queueTrigger}",
53+
"connection": "MyStorageConnectionAppSetting",
54+
"direction": "in"
55+
},
56+
{
57+
"name": "myOutputBlob",
58+
"type": "blob",
59+
"path": "samples-workitems/{queueTrigger}-Copy",
60+
"connection": "MyStorageConnectionAppSetting",
61+
"direction": "out"
62+
}
63+
],
64+
"disabled": false
65+
}
66+
```
67+
68+
The [configuration](#configuration) section explains these properties.
69+
70+
Here's the C# script code:
71+
72+
```cs
73+
public static void Run(string myQueueItem, string myInputBlob, out string myOutputBlob, ILogger log)
74+
{
75+
log.LogInformation($"C# Queue trigger function processed: {myQueueItem}");
76+
myOutputBlob = myInputBlob;
77+
}
78+
```
79+
80+
# [JavaScript](#tab/javascript)
81+
82+
<!--Same example for input and output. -->
83+
84+
The following example shows blob input and output bindings in a *function.json* file and [JavaScript code](functions-reference-node.md) that uses the bindings. The function makes a copy of a blob. The function is triggered by a queue message that contains the name of the blob to copy. The new blob is named *{originalblobname}-Copy*.
85+
86+
In the *function.json* file, the `queueTrigger` metadata property is used to specify the blob name in the `path` properties:
87+
88+
```json
89+
{
90+
"bindings": [
91+
{
92+
"queueName": "myqueue-items",
93+
"connection": "MyStorageConnectionAppSetting",
94+
"name": "myQueueItem",
95+
"type": "queueTrigger",
96+
"direction": "in"
97+
},
98+
{
99+
"name": "myInputBlob",
100+
"type": "blob",
101+
"path": "samples-workitems/{queueTrigger}",
102+
"connection": "MyStorageConnectionAppSetting",
103+
"direction": "in"
104+
},
105+
{
106+
"name": "myOutputBlob",
107+
"type": "blob",
108+
"path": "samples-workitems/{queueTrigger}-Copy",
109+
"connection": "MyStorageConnectionAppSetting",
110+
"direction": "out"
111+
}
112+
],
113+
"disabled": false
114+
}
115+
```
116+
117+
The [configuration](#configuration) section explains these properties.
118+
119+
Here's the JavaScript code:
120+
121+
```javascript
122+
module.exports = function(context) {
123+
context.log('Node.js Queue trigger function processed', context.bindings.myQueueItem);
124+
context.bindings.myOutputBlob = context.bindings.myInputBlob;
125+
context.done();
126+
};
127+
```
128+
129+
# [Python](#tab/python)
130+
131+
<!--Same example for input and output. -->
132+
133+
The following example shows blob input and output bindings in a *function.json* file and [Python code](functions-reference-python.md) that uses the bindings. The function makes a copy of a blob. The function is triggered by a queue message that contains the name of the blob to copy. The new blob is named *{originalblobname}-Copy*.
134+
135+
In the *function.json* file, the `queueTrigger` metadata property is used to specify the blob name in the `path` properties:
136+
137+
```json
138+
{
139+
"bindings": [
140+
{
141+
"queueName": "myqueue-items",
142+
"connection": "MyStorageConnectionAppSetting",
143+
"name": "queuemsg",
144+
"type": "queueTrigger",
145+
"direction": "in"
146+
},
147+
{
148+
"name": "inputblob",
149+
"type": "blob",
150+
"path": "samples-workitems/{queueTrigger}",
151+
"connection": "MyStorageConnectionAppSetting",
152+
"direction": "in"
153+
},
154+
{
155+
"name": "$return",
156+
"type": "blob",
157+
"path": "samples-workitems/{queueTrigger}-Copy",
158+
"connection": "MyStorageConnectionAppSetting",
159+
"direction": "out"
160+
}
161+
],
162+
"disabled": false,
163+
"scriptFile": "__init__.py"
164+
}
165+
```
166+
167+
The [configuration](#configuration) section explains these properties.
168+
169+
Here's the Python code:
170+
171+
```python
172+
import logging
173+
import azure.functions as func
174+
175+
176+
def main(queuemsg: func.QueueMessage, inputblob: func.InputStream) -> func.InputStream:
177+
logging.info('Python Queue trigger function processed %s', inputblob.name)
178+
return inputblob
179+
```
180+
181+
# [Java](#tab/java)
182+
183+
This section contains the following examples:
184+
185+
* [HTTP trigger, look up blob name from query string](#http-trigger-look-up-blob-name-from-query-string)
186+
* [Queue trigger, receive blob name from queue message](#queue-trigger-receive-blob-name-from-queue-message)
187+
188+
#### HTTP trigger, look up blob name from query string
189+
190+
The following example shows a Java function that uses the `HttpTrigger` annotation to receive a parameter containing the name of a file in a blob storage container. The `BlobInput` annotation then reads the file and passes its contents to the function as a `byte[]`.
191+
192+
```java
193+
@FunctionName("getBlobSizeHttp")
194+
@StorageAccount("Storage_Account_Connection_String")
195+
public HttpResponseMessage blobSize(
196+
@HttpTrigger(name = "req",
197+
methods = {HttpMethod.GET},
198+
authLevel = AuthorizationLevel.ANONYMOUS)
199+
HttpRequestMessage<Optional<String>> request,
200+
@BlobInput(
201+
name = "file",
202+
dataType = "binary",
203+
path = "samples-workitems/{Query.file}")
204+
byte[] content,
205+
final ExecutionContext context) {
206+
// build HTTP response with size of requested blob
207+
return request.createResponseBuilder(HttpStatus.OK)
208+
.body("The size of \"" + request.getQueryParameters().get("file") + "\" is: " + content.length + " bytes")
209+
.build();
210+
}
211+
```
212+
213+
#### Queue trigger, receive blob name from queue message
214+
215+
The following example shows a Java function that uses the `QueueTrigger` annotation to receive a message containing the name of a file in a blob storage container. The `BlobInput` annotation then reads the file and passes its contents to the function as a `byte[]`.
216+
217+
```java
218+
@FunctionName("getBlobSize")
219+
@StorageAccount("Storage_Account_Connection_String")
220+
public void blobSize(
221+
@QueueTrigger(
222+
name = "filename",
223+
queueName = "myqueue-items-sample")
224+
String filename,
225+
@BlobInput(
226+
name = "file",
227+
dataType = "binary",
228+
path = "samples-workitems/{queueTrigger}")
229+
byte[] content,
230+
final ExecutionContext context) {
231+
context.getLogger().info("The size of \"" + filename + "\" is: " + content.length + " bytes");
232+
}
233+
```
234+
235+
In the [Java functions runtime library](/java/api/overview/azure/functions/runtime), use the `@BlobInput` annotation on parameters whose value would come from a blob. This annotation can be used with native Java types, POJOs, or nullable values using `Optional<T>`.
236+
237+
---
238+
239+
## Attributes and annotations
240+
241+
# [C#](#tab/csharp)
242+
243+
In [C# class libraries](functions-dotnet-class-library.md), use the [BlobAttribute](https://github.com/Azure/azure-webjobs-sdk/blob/dev/src/Microsoft.Azure.WebJobs.Extensions.Storage/Blobs/BlobAttribute.cs).
244+
245+
The attribute's constructor takes the path to the blob and a `FileAccess` parameter indicating read or write, as shown in the following example:
246+
247+
```csharp
248+
[FunctionName("BlobInput")]
249+
public static void Run(
250+
[QueueTrigger("myqueue-items")] string myQueueItem,
251+
[Blob("samples-workitems/{queueTrigger}", FileAccess.Read)] Stream myBlob,
252+
ILogger log)
253+
{
254+
log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
255+
}
256+
257+
```
258+
259+
You can set the `Connection` property to specify the storage account to use, as shown in the following example:
260+
261+
```csharp
262+
[FunctionName("BlobInput")]
263+
public static void Run(
264+
[QueueTrigger("myqueue-items")] string myQueueItem,
265+
[Blob("samples-workitems/{queueTrigger}", FileAccess.Read, Connection = "StorageConnectionAppSetting")] Stream myBlob,
266+
ILogger log)
267+
{
268+
log.LogInformation($"BlobInput processed blob\n Name:{myQueueItem} \n Size: {myBlob.Length} bytes");
269+
}
270+
```
271+
272+
You can use the `StorageAccount` attribute to specify the storage account at class, method, or parameter level. For more information, see [Trigger - attributes and annotations](./functions-bindings-storage-blob-trigger.md#attributes-and-annotations).
273+
274+
# [C# Script](#tab/csharp-script)
275+
276+
Attributes are not supported by C# Script.
277+
278+
# [JavaScript](#tab/javascript)
279+
280+
Attributes are not supported by JavaScript.
281+
282+
# [Python](#tab/python)
283+
284+
Attributes are not supported by Python.
285+
286+
# [Java](#tab/java)
287+
288+
The `@BlobInput` attribute gives you access to the blob that triggered the function. If you use a byte array with the attribute, set `dataType` to `binary`. Refer to the [input example](#example) for details.
289+
290+
---
291+
292+
## Configuration
293+
294+
The following table explains the binding configuration properties that you set in the *function.json* file and the `Blob` attribute.
295+
296+
|function.json property | Attribute property |Description|
297+
|---------|---------|----------------------|
298+
|**type** | n/a | Must be set to `blob`. |
299+
|**direction** | n/a | Must be set to `in`. Exceptions are noted in the [usage](#usage) section. |
300+
|**name** | n/a | The name of the variable that represents the blob in function code.|
301+
|**path** |**BlobPath** | The path to the blob. |
302+
|**connection** |**Connection**| The name of an app setting that contains the [Storage connection string](../storage/common/storage-configure-connection-string.md) to use for this binding. If the app setting name begins with "AzureWebJobs", you can specify only the remainder of the name here. For example, if you set `connection` to "MyStorage", the Functions runtime looks for an app setting that is named "AzureWebJobsMyStorage." If you leave `connection` empty, the Functions runtime uses the default Storage connection string in the app setting that is named `AzureWebJobsStorage`.<br><br>The connection string must be for a general-purpose storage account, not a [blob-only storage account](../storage/common/storage-account-overview.md#types-of-storage-accounts).|
303+
|n/a | **Access** | Indicates whether you will be reading or writing. |
304+
305+
[!INCLUDE [app settings to local.settings.json](../../includes/functions-app-settings-local.md)]
306+
307+
## Usage
308+
309+
# [C#](#tab/csharp)
310+
311+
[!INCLUDE [functions-bindings-blob-storage-input-usage.md](../../includes/functions-bindings-blob-storage-input-usage.md)]
312+
313+
# [C# Script](#tab/csharp-script)
314+
315+
[!INCLUDE [functions-bindings-blob-storage-input-usage.md](../../includes/functions-bindings-blob-storage-input-usage.md)]
316+
317+
# [JavaScript](#tab/javascript)
318+
319+
Access blob data using `context.bindings.<NAME>` where `<NAME>` matches the value defined in *function.json*.
320+
321+
# [Python](#tab/python)
322+
323+
Access blob data via the parameter typed as [InputStream](https://docs.microsoft.com/python/api/azure-functions/azure.functions.inputstream?view=azure-python). Refer to the [input example](#example) for details.
324+
325+
# [Java](#tab/java)
326+
327+
The `@BlobInput` attribute gives you access to the blob that triggered the function. If you use a byte array with the attribute, set `dataType` to `binary`. Refer to the [input example](#example) for details.
328+
329+
---
330+
331+
## Next steps
332+
333+
- [Run a function when blob storage data changes](./functions-bindings-storage-blob-trigger.md)
334+
- [Write blob storage data from a function](./functions-bindings-storage-blob-output.md)

0 commit comments

Comments
 (0)