Skip to content

Latest commit

 

History

History
253 lines (217 loc) · 13.5 KB

README.md

File metadata and controls

253 lines (217 loc) · 13.5 KB
Raw

Redis Extension for Azure Functions

Introduction

This repository contains the bindings to use in your Azure Functions and WebJobs.

There are five bindings in this extension:

Getting Started

See the following docs for details on setup and samples of the Redis triggers:

Usage

RedisPubSubTrigger

The RedisPubSubTrigger subscribes to a Redis pub/sub channel and surfaces messages received to the function.

Note This trigger is only available on the Premium plan and Dedicated plan because Redis pub/sub requires clients to always be actively listening to receive all messages. There is a chance your function may miss messages on a consumption plan.

Note Functions with this trigger should not be scaled out to multiple instances. Each instance will trigger on each message from the channel, resulting in duplicate processing.

Note This trigger is not capable of listening to keyspace notifications on clustered caches.

Inputs

  • Connection: App setting name that contains Redis connection information.
  • Channel: Redis pubsub channel that the trigger will listen to.
  • Pattern: If the channel is a pattern.
    • Default: false

Available Parameter Types

  • Types exclusive to dotnet in-process
  • Types available to all (dotnet in-process, dotnet out-of-process, python, node, java, powershell, etc)
    • string, byte[]/ReadOnlyMemory<byte>: The channel message serialized as JSON (UTF-8 encoded for byte types) in the following format: 
      {
  "SubscriptionChannel":"__keyspace@0__:*",
  "Channel":"__keyspace@0__:mykey",
  "Message":"set"
}
    • Custom: The trigger uses Json.NET serialization to map string value into the given custom type.

Sample

The following sample listens to the channel pubsubTest.

[FunctionName(nameof(PubSubTrigger))]
public static void PubSubTrigger(
    [RedisPubSubTrigger("Redis", "pubsubTest")] string message,
    ILogger logger)
{
    logger.LogInformation($"The message broadcast to channel 'pubsubTest': '{message}'");
}

RedisListTrigger

The RedisListTrigger pops entries from a list and surfaces those entries to the function. The trigger polls Redis at a configurable fixed interval, and uses LPOP/RPOP to pop entries from the lists.

Inputs

  • Connection: App setting name that contains Redis connection information.
  • Key: Key to read from.
  • PollingIntervalInMs: How often to poll Redis in milliseconds.
    • Default: 1000
  • MaxBatchSize: Number of entries to pop from the Redis list at one time. These are usually processed in parallel, with each entry from the list triggering its own function invocation. If a dotnet in-process function defines the parameter type as RedisValue[], string[], or byte[][], there will only be one function invocation with all entries returned as this array type.
    • Only supported on Redis 6.2+ using the COUNT argument in LPOP/RPOP.
    • Default: 16
  • ListDirection: The direction to pop elements from the list: LEFT using LPOP or RIGHT using RPOP.
    • Allowed Values: LEFT, RIGHT
    • Default: LEFT

Available Parameter Types

  • Types exclusive to dotnet in-process
    • RedisValue: The entry from the list.
    • Single-invocation batch types: RedisValue[], string[], byte[][] - The full batch of list entries given to the function in one invocation.
  • Types available to all (dotnet in-process, dotnet out-of-process, python, node, java, powershell, etc)
    • string, byte[]/ReadOnlyMemory<byte>: The entry from the list.
    • Custom: The trigger uses Json.NET serialization to map string value into the given custom type.

Sample

The following sample polls the key listTest.

[FunctionName(nameof(ListsTrigger))]
public static void ListsTrigger(
    [RedisListTrigger("Redis", "listTest")] string entry,
    ILogger logger)
{
    logger.LogInformation($"The entry pushed to the list 'listTest': '{entry}'");
}

RedisStreamTrigger

The RedisStreamTrigger reads entries from a stream and surfaces those entries to the function. The trigger polls Redis at a configurable fixed interval, and uses XREADGROUP to read entries from the stream. The consumer group for all instances of a function will be the name of the function (e.g. SimpleStreamTrigger for this sample). Each functions instance will use the WEBSITE_INSTANCE_ID (documented here) or generate a random GUID to use as its consumer name within the group to ensure that scaled out instances of the function will not read the same messages from the stream.

Inputs

  • Connection: App setting name that contains Redis connection information.
  • Key: Key to read from.
  • PollingIntervalInMs: How often to poll Redis in milliseconds.
    • Default: 1000
  • MaxBatchSize: Number of entries to read from Redis at one time. These are usually processed in parallel, with each entry from the list triggering its own function invocation. If a dotnet in-process function defines the parameter type as StreamEntry[], NameValueEntry[][], Dictionary<string, string>[], string[], or byte[][], there will only be one function invocation with all entries returned as this array type.
    • Default: 16

Available Parameter Types

  • Types exclusive to dotnet in-process
  • Types available to all (dotnet in-process, dotnet out-of-process, python, node, java, powershell, etc)
    • string, byte[], ReadOnlyMemory<byte>: The stream entry serialized as JSON (UTF-8 encoded for byte types) in the following format: 
      {
  "Id":"1658354934941-0",
  "Values":
  {
    "field1":"value1",
    "field2":"value2",
    "field3":"value3"
  }
}
    • Custom: The trigger uses Json.NET serialization to map string value into the given custom type.

Sample

The following sample polls the key streamTest.

[FunctionName(nameof(StreamsTrigger))]
public static void StreamsTrigger(
    [RedisStreamTrigger("Redis", "streamTest")] string entry,
    ILogger logger)
{
    logger.LogInformation($"The entry pushed to the stream 'streamTest': '{entry}'");
}

RedisInput Input Binding

Inputs

  • Connection: App setting name that contains Redis connection information.
  • Command: The redis-cli command to be executed on the cache with all arguments separated by spaces. (e.g. "GET key", "HGET key field")

Note Not all commands are supported for this binding. At the moment, only read commands that return a single output are supported. The full list can be found here

Available Parameter Types

  • RedisValue, string, byte[], ReadOnlyMemory<byte>: The value returned by the command.
  • Custom: The trigger uses Json.NET serialization to map the value returned by the command from a string into a custom type.

Sample

The following gets any key that was recently set.

[FunctionName(nameof(SetGetter))]
public static void SetGetter(
    [RedisPubSubTrigger("Redis", "__keyevent@0__:set")] string key,
    [Redis("Redis", "GET {Message}")] string value,
    ILogger logger)
{
    logger.LogInformation($"Key '{key}' was set to value '{value}'");
}

RedisOutput Output Binding

Inputs

  • Connection: App setting name that contains Redis connection information.
  • Command: The Redis command to be executed on the cache without any arguments. (e.g. "GET", "HGET")

Note All commands are supported for this binding.

Function Return type

  • string: Space-delimited arguments for the redis command.

Sample

The following deletes any key that was recently set.

[FunctionName(nameof(SetDeleter))]
public static void SetDeleter(
    [RedisPubSubTrigger("Redis", "__keyevent@0__:set")] string key,
    [Redis("Redis", "DEL")] out string arguments,
    ILogger logger)
{
    logger.LogInformation($"Deleting recently SET key '{key}'");
    arguments = key;
}

Connection Types

There are three types of connections that are allowed from an Azure Functions instane to a Redis Cache. In the appsettings, this is how to configure each of the following types of client authentication, assuming the Connection was set to "Redis" in the function.

  1. Connection String

    "Redis": "<cacheName>.redis.cache.windows.net:6380,password=..."

  2. System-Assigned Managed Identity

    "Redis:redisHostName": "<cacheName>.redis.cache.windows.net",
"Redis:principalId": "<principalId>"

  3. User-Assigned Managed Identity

    "Redis:redisHostName": "<cacheName>.redis.cache.windows.net",
"Redis:principalId": "<principalId>",
"Redis:clientId": "<clientId>"

  4. Service Principal Secret

    Note Connections using Service Principal Secrets are only available during local development.

    "Redis:redisHostName": "<cacheName>.redis.cache.windows.net",
"Redis:principalId": "<principalId>",
"Redis:clientId": "<clientId>"
"Redis:tenantId": "<tenantId>"
"Redis:clientSecret": "<clientSecret>"

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.