Odolné entity

Important

Support pro model v procesu skončí 10. listopadu 2026. Důrazně doporučujeme migrovat aplikace do izolovaného modelu pracovních procesů pro plnou podporu.

Funkce entit definují operace, které čtou a aktualizují malé části stavu označované jako odolné entity. Podobně jako funkce orchestrátoru používají funkce entit speciální typ triggeru označovaný jako trigger entity. Na rozdíl od funkcí orchestrátoru funkce entit spravují stav entity explicitně místo toho, aby představovaly stav prostřednictvím toku řízení. Entity pomáhají škálovat aplikace tak, že distribuují práci napříč mnoha entitami, z nichž každá má skromný stav.

Entity definují operace, které čtou a aktualizují malé části stavu, označované jako odolné entity. Na rozdíl od orchestrátorů entity spravují stav explicitně místo toho, aby představovaly stav prostřednictvím toku řízení. Entity pomáhají škálovat aplikace tak, že distribuují práci napříč mnoha entitami, z nichž každá má skromný stav.

Podpora trvalých entit

Funkce entit a související funkce jsou k dispozici v Durable Functions 2.0 a novějších verzích.

Programovací jazyk	Podpora trvalých entit
.NET izolované	✅
.NET v procesu	✅
Java	✅
Python	✅
JavaScript	✅
PowerShell	❌

SDK pro trvalé úkoly	Podpora trvalých entit
.NET izolované	✅
.NET v procesu	✅
Java	✅
Python	✅
JavaScript	✅
PowerShell	❌

Obecné koncepty trvalých entit

Entity fungují jako malé služby, které komunikují pomocí zpráv. Každá entita má jedinečnou identitu a v případě potřeby interní stav. Entity spouští operace po zobrazení výzvy. Operace může aktualizovat stav, volat externí služby nebo čekat na odpověď. Entity komunikují s jinými entitami, orchestracemi a klienty prostřednictvím zpráv, které modul runtime odesílá prostřednictvím spolehlivých front.

Aby se zabránilo konfliktům, jedna entita spouští operace sériově, jeden po druhém.

Poznámka:

Když vyvoláte entitu, zpracuje datovou část na dokončení a pak naplánuje nové spuštění, které se aktivuje při přijetí nového vstupu. V důsledku toho se po každém vyvolání může v protokolech spuštění entity zobrazit další spuštění. To se očekávalo.

ID subjektu

Pro přístup k entitě použijte ID entity . ID entity je dvojice řetězců, které jednoznačně identifikují instanci entity. Skládá se z:

• Název entity, který identifikuje typ entity. Například: Counter. Tento název odpovídá názvu funkce entity, která entitu implementuje. Nerozlišuje malá a velká písmena.
• Klíč entity, který jednoznačně identifikuje entitu mezi všemi ostatními entitami se stejným názvem. Například GUID.

Counter Například funkce entity se může použít k udržení skóre v online hře. Každá instance hry má jedinečné ID entity, například @Counter@Game1 a @Counter@Game2. Pokud chcete cílovou entitu, zadejte JEJÍ ID entity.

Operace entit

Pokud chcete vyvolat operaci u entity, zadejte:

• Identifikátor entity cílové entity.
• Název operace, což je řetězec, který určuje operaci, která se má provést. Entita Counter může například podporovat add, getnebo reset operace.
• Vstup operace, což je volitelný parametr operace. add Například operace přebírá jako vstup celočíselnou hodnotu.
• Naplánovaný čas, což je volitelný parametr, který určuje dobu doručení operace. Naplánujte například operaci tak, aby se spustila o několik dní později.

Operace můžou vrátit výslednou hodnotu nebo chybový výsledek, například chybu JavaScriptu nebo výjimku .NET. Orchestrace volání obdrží výsledek nebo chybu.

Operace můžou vrátit výslednou hodnotu nebo chybový výsledek, například výjimku .NET nebo výjimku Python. Volající obdrží výsledek nebo chybu.

Operace entity může také vytvořit, číst, aktualizovat a odstranit stav entity. Modul runtime vždy udržuje stav entity v úložišti.

Definování entit

C#

K definování entit v .NET použijte jedno ze dvou rozhraní API:

Syntaxe založená na funkcích: V syntaxi založené na funkcích napíšete každou entitu jako funkci a operace odesílání v aplikaci. Tato syntaxe funguje dobře pro entity s jednoduchým stavem, několika operacemi nebo dynamickou sadou operací, jako jsou v architekturách aplikací. Udržování však může být únavné, protože nezachytává chyby typu v době kompilace.

Třídní syntaxe: V syntaxi založené na třídě .NET třídy a metody modelují entity a operace modelu. Tato syntaxe usnadňuje čtení kódu a umožňuje volat operace bezpečným způsobem. Je to tenká vrstva nad syntaxí založenou na funkcích, takže můžete kombinovat obě varianty ve stejné aplikaci.

Rozhraní API, která používáte, závisí na tom, kde běží funkce jazyka C#. Doporučuje se izolovaný pracovní proces , ale můžete ho spustit také v hostitelském procesu.

Izolovaný příklad založený na funkci pracovního procesu

Následující příklad ukazuje entitu založenou na Counter funkci v izolovaném pracovním procesu. Podporuje add, reset, geta delete.

[Function(nameof(Counter))]
public static Task Counter([EntityTrigger] TaskEntityDispatcher dispatcher)
{
    return dispatcher.DispatchAsync(operation =>
    {
        if (operation.State.GetState(typeof(int)) is null)
        {
            operation.State.SetState(0);
        }

        switch (operation.Name.ToLowerInvariant())
        {
            case "add":
                int state = operation.State.GetState<int>();
                state += operation.GetInput<int>();
                operation.State.SetState(state);
                return new(state);
            case "reset":
                operation.State.SetState(0);
                break;
            case "get":
                return new(operation.State.GetState<int>());
            case "delete":
                operation.State.SetState(null);
                break;
        }

        return default;
    });
}

Příklad založený na třídě izolovaného pracovního procesu

Následující příklad ukazuje implementaci Counter entity pomocí tříd a metod.

public class Counter : TaskEntity<int>
{
    readonly ILogger logger;

    public Counter(ILogger<Counter> logger)
    {
        this.logger = logger;
    }

    public void Add(int amount) => this.State += amount;

    public void Reset() => this.State = 0;

    public int Get() => this.State;

    [Function(nameof(Counter))]
    public Task RunEntityAsync([EntityTrigger] TaskEntityDispatcher dispatcher)
    {
        return dispatcher.DispatchAsync(this);
    }
}

Příklad založený na funkcích během procesu

Tento příklad ukazuje jednoduchou Counter entitu implementovanou jako odolnou funkci. Definuje tři operace –addreset a get– které používají celočíselné stavy.

[FunctionName("Counter")]
public static void Counter([EntityTrigger] IDurableEntityContext ctx)
{
    switch (ctx.OperationName.ToLowerInvariant())
    {
        case "add":
            ctx.SetState(ctx.GetState<int>() + ctx.GetInput<int>());
            break;
        case "reset":
            ctx.SetState(0);
            break;
        case "get":
            ctx.Return(ctx.GetState<int>());
            break;
    }
}

Další informace najdete v tématu Syntaxe založená na funkcích.

Příklad založený na třídě během procesu

Tento příklad ukazuje stejnou Counter entitu implementovanou pomocí tříd a metod.

[JsonObject(MemberSerialization.OptIn)]
public class Counter
{
    [JsonProperty("value")]
    public int CurrentValue { get; set; }

    public void Add(int amount) => this.CurrentValue += amount;

    public void Reset() => this.CurrentValue = 0;

    public int Get() => this.CurrentValue;

    [FunctionName(nameof(Counter))]
    public static Task Run([EntityTrigger] IDurableEntityContext ctx)
        => ctx.DispatchAsync<Counter>();
}

Tato entita ukládá stav do objektu Counter , který obsahuje aktuální hodnotu čítače. Durable Functions serializuje a deserializuje tento objekt pomocí knihovny Json.NET.

Další informace naleznete v tématu Definování tříd entit.

JavaScript

JavaScript podporuje odolné entity od verze 1.3.0 balíčku durable-functions npm. Tento příklad ukazuje entitu Counter implementovanou jako odolnou funkci v JavaScriptu.

Čítač/function.json

{
  "bindings": [
    {
      "name": "context",
      "type": "entityTrigger",
      "direction": "in"
    }
  ],
  "disabled": false
}

Čítač/index.js

const df = require("durable-functions");

module.exports = df.entity(function(context) {
    const currentValue = context.df.getState(() => 0);
    switch (context.df.operationName) {
        case "add": {
            const amount = context.df.getInput();
            context.df.setState(currentValue + amount);
            break;
        }
        case "reset":
            context.df.setState(0);
            break;
        case "get":
            context.df.return(currentValue);
            break;
    }
});

Python

Následující kód ukazuje entitu Counter implementovanou jako trvalou funkci napsanou v Pythonu.

import azure.functions as func
import azure.durable_functions as df

# Entity function called counter
@myApp.entity_trigger(context_name="context")
def Counter(context):
    current_value = context.get_state(lambda: 0)
    operation = context.operation_name
    if operation == "add":
        amount = context.get_input()
        current_value += amount
    elif operation == "reset":
        current_value = 0
    elif operation == "get":
        context.set_result(current_value)
    context.set_state(current_value)

PowerShell

PowerShell momentálně nepodporuje funkce entit.

Java

Od verze 1.9.0 podporuje Durable Functions for Java definování entit pomocí syntaxe založené na třídách. Základní třídu můžete rozšířit AbstractTaskEntity<TState> tak, aby definovala entitu.

Následující příklad ukazuje entitu Counter implementovanou jako odolnou funkci v Java.

Třída entity:

import com.microsoft.durabletask.AbstractTaskEntity;
import com.microsoft.durabletask.TaskEntityOperation;

public class CounterEntity extends AbstractTaskEntity<Integer> {

    public void add(int value) {
        this.state += value;
    }

    public void subtract(int value) {
        this.state -= value;
    }

    public int get() {
        return this.state;
    }

    public void reset() {
        this.state = 0;
    }

    @Override
    protected Integer initializeState(TaskEntityOperation operation) {
        return 0;
    }

    @Override
    protected Class<Integer> getStateType() {
        return Integer.class;
    }
}

Funkce entity:

@FunctionName("Counter")
public String counterEntity(
    @DurableEntityTrigger(name = "req") String req) {
    return EntityRunner.loadAndRun(req, CounterEntity::new);
}

C#

Sada Durable Task SDK pro .NET podporuje definování entit pomocí syntaxe založené na třídách. Implementujte základní třídu TaskEntity<TState> pro definování vaší entity.

Následující příklad ukazuje entitu Counter implementovanou pomocí sady Durable Task SDK:

using Microsoft.DurableTask.Entities;

public class Counter : TaskEntity<int>
{
    public void Add(int amount) => this.State += amount;

    public void Reset() => this.State = 0;

    public int Get() => this.State;
}

Registrace entity u pracovníka:

builder.Services.AddDurableTaskWorker()
    .AddTasks(registry =>
    {
        registry.AddEntity<Counter>();
    })
    .UseDurableTaskScheduler(connectionString);

Signál nebo volání entity z orchestrátoru:

public class EntityOrchestration : TaskOrchestrator<string, int>
{
    public override async Task<int> RunAsync(TaskOrchestrationContext context, string entityKey)
    {
        var entityId = new EntityInstanceId(nameof(Counter), entityKey);

        // Signal the entity (fire-and-forget)
        await context.Entities.SignalEntityAsync(entityId, nameof(Counter.Add), 1);

        // Call the entity and wait for response
        int currentValue = await context.Entities.CallEntityAsync<int>(entityId, nameof(Counter.Get));

        return currentValue;
    }
}

JavaScript

Sada Durable Task SDK pro JavaScript/TypeScript podporuje definování entit pomocí syntaxe založené na třídách. Rozšiřte základní třídu TaskEntity<TState> pro definici vaší entity.

Následující příklad ukazuje entitu Counter implementovanou pomocí sady Durable Task SDK:

import { TaskEntity } from "@microsoft/durabletask-js";

class CounterEntity extends TaskEntity {
  add(amount) {
    this.state.value += amount;
    return this.state.value;
  }

  get() {
    return this.state.value;
  }

  reset() {
    this.state.value = 0;
  }

  initializeState() {
    return { value: 0 };
  }
}

Registrace entity u pracovníka:

worker.addNamedEntity("Counter", () => new CounterEntity());

Python

Sada Durable Task SDK pro Python podporuje definování entit pomocí syntaxe založené na funkcích.

Následující příklad ukazuje entitu Counter implementovanou pomocí sady Durable Task SDK:

from durabletask import task

def counter_entity(ctx: task.EntityContext):
    """Counter entity that maintains an integer state."""
    current_value = ctx.get_state(lambda: 0)
    operation = ctx.operation_name

    if operation == "add":
        amount = ctx.get_input()
        current_value += amount
    elif operation == "reset":
        current_value = 0
    elif operation == "get":
        ctx.set_result(current_value)

    ctx.set_state(current_value)

Registrace entity u pracovníka:

with DurableTaskSchedulerWorker(
    host_address=endpoint,
    secure_channel=secure_channel,
    taskhub=taskhub,
    token_credential=credential
) as worker:
    worker.add_entity(counter_entity)
    worker.start()

PowerShell

Podpora PowerShellu pro odolné entity zatím není dostupná. Zkontrolujte budoucí aktualizace.

Java

Sada Durable Task SDK pro Javu podporuje definování entit pomocí syntaxe založené na třídě. Základní třídu můžete rozšířit AbstractTaskEntity<TState> tak, aby definovala entitu.

Následující příklad ukazuje entitu Counter implementovanou pomocí sady Durable Task SDK:

import com.microsoft.durabletask.AbstractTaskEntity;
import com.microsoft.durabletask.TaskEntityOperation;

public class CounterEntity extends AbstractTaskEntity<Integer> {

    public void add(int amount) {
        this.state += amount;
    }

    public void reset() {
        this.state = 0;
    }

    public int get() {
        return this.state;
    }

    @Override
    protected Integer initializeState(TaskEntityOperation operation) {
        return 0;
    }

    @Override
    protected Class<Integer> getStateType() {
        return Integer.class;
    }
}

Registrace entity u pracovníka:

DurableTaskGrpcWorker worker = new DurableTaskGrpcWorkerBuilder()
        .addEntity("Counter", CounterEntity::new)
        .build();

worker.start();

Signál nebo volání entity z orchestrátoru:

return ctx -> {
    EntityInstanceId counterId = new EntityInstanceId("Counter", "myCounter");

    // Signal the entity (fire-and-forget)
    ctx.signalEntity(counterId, "add", 5);

    // Call the entity and wait for response
    int currentValue = ctx.callEntity(counterId, "get", Integer.class).await();

    ctx.complete(currentValue);
};

Přístup k entitám

Přístup k entitě pomocí jednosměrné nebo obousměrné komunikace:

• Volání entity používá obousměrnou (zpáteční) komunikaci. Odešlete do entity zprávu operace a pak počkejte na zprávu odpovědi, než budete pokračovat. Zpráva odpovědi poskytuje výslednou hodnotu nebo chybu (například javascriptovou chybu nebo výjimku .NET).
• Signalizace entita používá jednostrannou (fire and forget) komunikaci. Odešlete provozní zprávu a nečekejte na odpověď. Modul runtime zaručuje doručení, ale odesílatel nemůže sledovat výsledné hodnoty nebo chyby.

Získejte přístup k entitě z klientských funkcí, funkcí orchestrátoru nebo funkcí entit. Ne každý kontext podporuje oba typy komunikace:

• Klientské funkce podporují signalizační entity a čtení stavu entit.
• Funkce orchestratoru podporují signalizaci a volání entit.
• Funkce entit podporují signalizační entity.

Přístup k entitě pomocí jednosměrné nebo obousměrné komunikace:

• Volání entity používá obousměrnou (zpáteční) komunikaci. Odešlete do entity zprávu operace a pak počkejte na zprávu odpovědi, než budete pokračovat. Zpráva odpovědi obsahuje výslednou hodnotu nebo chybu.
• Signalizace entita používá jednostrannou (fire and forget) komunikaci. Odešlete provozní zprávu a nečekejte na odpověď. Modul runtime zaručuje doručení, ale odesílatel nemůže sledovat výsledné hodnoty nebo chyby.

Přístup k entitám od klientů nebo orchestrátorů Ne každý kontext podporuje oba typy komunikace:

• Klienti podporují signalizační funkce entit a čtení stavů entit.
• Orchestrátory podporují signalizaci a volání entit.

Následující příklady ukazují, jak získat přístup k entitě.

Příklad: Klient signalizuje entitu

Pokud chcete získat přístup k entitě z běžné funkce Azure, která se označuje také jako klientská funkce, použijte vazbu klienta entity. Následující příklad ukazuje funkci spouštěnou frontou, která signalizuje entitu pomocí tohoto navázání.

C#

Poznámka:

Pro zjednodušení následující příklady ukazují volně napsanou syntaxi pro přístup k entitě. Obecně platí, že přistupují k entitám prostřednictvím rozhraní , protože poskytují větší kontrolu typů.

V procesu:

V procesu:

[FunctionName("AddFromQueue")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] IDurableEntityClient client)
{
    // Entity operation input comes from the queue message content.
    var entityId = new EntityId(nameof(Counter), "myCounter");
    int amount = int.Parse(input);
    return client.SignalEntityAsync(entityId, "Add", amount);
}

Izolovaný pracovní proces:

[Function("AddFromQueue")]
public static Task Run(
    [QueueTrigger("durable-function-trigger")] string input,
    [DurableClient] DurableTaskClient client)
{
    // Entity operation input comes from the queue message content.
    var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
    int amount = int.Parse(input);
    return client.Entities.SignalEntityAsync(entityId, "Add", amount);
}

JavaScript

const df = require("durable-functions");

module.exports = async function (context) {
    const client = df.getClient(context);
    const entityId = new df.EntityId("Counter", "myCounter");
    await client.signalEntity(entityId, "add", 1);
};

Python

import azure.functions as func
import azure.durable_functions as df

# An HTTP-Triggered Function with a Durable Functions Client to set a value on a durable entity
@myApp.route(route="entitysetvalue")
@myApp.durable_client_input(client_name="client")
async def http_set(req: func.HttpRequest, client):
    entityId = df.EntityId("Counter", "myCounter")
    await client.signal_entity(entityId, "add", 1)
    return func.HttpResponse("Done", status_code=200)

PowerShell

PowerShell momentálně nepodporuje funkce entit.

Java

@FunctionName("SignalCounter")
public HttpResponseMessage signalCounter(
    @HttpTrigger(name = "req", methods = {HttpMethod.POST},
        authLevel = AuthorizationLevel.ANONYMOUS)
    HttpRequestMessage<Void> request,
    @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {

    String entityKey = request.getQueryParameters().getOrDefault("key", "myCounter");
    String operation = request.getQueryParameters().getOrDefault("op", "add");
    String valueStr = request.getQueryParameters().getOrDefault("value", "1");

    EntityInstanceId entityId = new EntityInstanceId("Counter", entityKey);

    if ("reset".equals(operation)) {
        durableContext.signalEntity(entityId, operation);
    } else {
        int value = Integer.parseInt(valueStr);
        durableContext.signalEntity(entityId, operation, value);
    }

    return request.createResponseBuilder(HttpStatus.ACCEPTED)
        .body("Signal sent: " + operation + " on entity '" + entityKey + "'")
        .build();
}

Termín signál znamená, že volání rozhraní API entity je jednosměrné a asynchronní. Klientská funkce nemůže vědět, kdy entita zpracuje operaci. Funkce klienta nemůže sledovat výsledné hodnoty nebo výjimky.

Pokud chcete získat přístup k entitám z klienta, použijte DurableTaskClient k signalizaci nebo ke čtení stavu entity.

C#

// Signal an entity
var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
await client.Entities.SignalEntityAsync(entityId, nameof(Counter.Add), 1);

JavaScript

// Signal an entity
const counterId = new EntityInstanceId("Counter", "myCounter");
await client.signalEntity(counterId, "add", 1);

Python

# Signal an entity
entity_id = EntityId("Counter", "myCounter")
client.signal_entity(entity_id, "add", 1)

PowerShell

Podpora PowerShellu pro odolné entity zatím není dostupná. Zkontrolujte budoucí aktualizace.

Java

// Signal an entity
EntityInstanceId counterId = new EntityInstanceId("Counter", "myCounter");
client.getEntities().signalEntity(counterId, "add", 1);

Termín signál znamená, že volání rozhraní API entity je jednosměrné a asynchronní. Klient nemůže vědět, kdy entita zpracuje operaci.

Příklad: Klient přečte stav entity.

Dotazování stavu entity z klientské funkce:

C#

V procesu:

[FunctionName("QueryCounter")]
public static async Task<HttpResponseMessage> Run(
    [HttpTrigger(AuthorizationLevel.Function)] HttpRequestMessage req,
    [DurableClient] IDurableEntityClient client)
{
    var entityId = new EntityId(nameof(Counter), "myCounter");
    EntityStateResponse<JObject> stateResponse = await client.ReadEntityStateAsync<JObject>(entityId);
    return req.CreateResponse(HttpStatusCode.OK, stateResponse.EntityState);
}

Izolovaný pracovní proces:

[Function("QueryCounter")]
public static async Task<HttpResponseData> Run(
    [HttpTrigger(AuthorizationLevel.Function)] HttpRequestData req,
    [DurableClient] DurableTaskClient client)
{
    var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
    EntityMetadata<int>? entity = await client.Entities.GetEntityAsync<int>(entityId);

    if (entity is null)
    {
        return req.CreateResponse(HttpStatusCode.NotFound);
    }

    HttpResponseData response = req.CreateResponse(HttpStatusCode.OK);
    await response.WriteAsJsonAsync(entity);

    return response;
}

JavaScript

const df = require("durable-functions");

module.exports = async function (context) {
    const client = df.getClient(context);
    const entityId = new df.EntityId("Counter", "myCounter");
    const stateResponse = await client.readEntityState(entityId);
    return stateResponse.entityState;
};

Python

# An HTTP-Triggered Function with a Durable Functions Client to retrieve the state of a durable entity
@myApp.route(route="entityreadvalue")
@myApp.durable_client_input(client_name="client")
async def http_read(req: func.HttpRequest, client):
    entityId = df.EntityId("Counter", "myCounter")
    entity_state_result = await client.read_entity_state(entityId)
    entity_state = "No state found"
    if entity_state_result.entity_exists:
      entity_state = str(entity_state_result.entity_state)
    return func.HttpResponse(entity_state)

PowerShell

PowerShell momentálně nepodporuje funkce entit.

Java

@FunctionName("GetCounter")
public HttpResponseMessage getCounter(
    @HttpTrigger(name = "req", methods = {HttpMethod.GET},
        authLevel = AuthorizationLevel.ANONYMOUS)
    HttpRequestMessage<Void> request,
    @DurableClientInput(name = "durableContext") DurableClientContext durableContext) {

    String entityKey = request.getQueryParameters().getOrDefault("key", "myCounter");
    EntityInstanceId entityId = new EntityInstanceId("Counter", entityKey);

    EntityMetadata metadata = durableContext.getEntityMetadata(entityId, true);

    if (metadata == null) {
        return request.createResponseBuilder(HttpStatus.NOT_FOUND)
            .body("Entity '" + entityKey + "' not found")
            .build();
    }

    Integer state = metadata.readStateAs(Integer.class);
    return request.createResponseBuilder(HttpStatus.OK)
        .header("Content-Type", "application/json")
        .body("{\"key\": \"" + entityKey + "\", \"value\": " + state + "}")
        .build();
}

Klienti můžou dotazovat stav entity:

C#

var entityId = new EntityInstanceId(nameof(Counter), "myCounter");
EntityMetadata<int>? entity = await client.Entities.GetEntityAsync<int>(entityId);

if (entity != null)
{
    Console.WriteLine($"Current value: {entity.State}");
}

JavaScript

const counterId = new EntityInstanceId("Counter", "myCounter");
const metadata = await client.getEntity(counterId);

if (metadata.exists) {
  console.log(`Current value: ${metadata.state?.value}`);
}

Python

entity_id = EntityId("Counter", "myCounter")
state = client.get_entity_state(entity_id)
if state is not None:
    print(f"Current value: {state}")

PowerShell

Podpora PowerShellu pro odolné entity zatím není dostupná. Zkontrolujte budoucí aktualizace.

Java

EntityInstanceId counterId = new EntityInstanceId("Counter", "myCounter");
EntityMetadata entityMetadata = client.getEntities().getEntityMetadata(counterId, true);

if (entityMetadata != null) {
    Integer state = entityMetadata.readStateAs(Integer.class);
    System.out.printf("Current value: %d%n", state);
}

Dotazy na stav entity jdou do trvalého sledovacího úložiště a vracejí naposledy zachovaný stav entity. Tento stav je vždy ve stavu „committed“, takže nikdy nejde o dočasný mezistav, do něhož se systém přechodně dostává během provádění operace. Tento stav ale může být v porovnání se stavem v paměti entity zastaralý. Orchestrace můžou číst pouze stav v paměti entity, jak je popsáno v následující části.

Příklad: Orchestrační signály a volání entity

Funkce orchestratoru mají přístup k entitám pomocí rozhraní API na vazbě triggeru orchestrace. Následující příklad kódu ukazuje orchestrační funkci volající a signalizující Counter entitu.

C#

V procesu:

[FunctionName("CounterOrchestration")]
public static async Task Run(
    [OrchestrationTrigger] IDurableOrchestrationContext context)
{
    var entityId = new EntityId(nameof(Counter), "myCounter");

    // Two-way call to the entity which returns a value - awaits the response
    int currentValue = await context.CallEntityAsync<int>(entityId, "Get");
    if (currentValue < 10)
    {
        // One-way signal to the entity which updates the value - does not await a response
        context.SignalEntity(entityId, "Add", 1);
    }
}

Izolovaný pracovní proces:

[Function("CounterOrchestration")]
public static async Task Run([OrchestrationTrigger] TaskOrchestrationContext context)
{
    var entityId = new EntityInstanceId(nameof(Counter), "myCounter");

    // Two-way call to the entity which returns a value - awaits the response
    int currentValue = await context.Entities.CallEntityAsync<int>(entityId, "Get");

    if (currentValue < 10)
    {
        // One-way signal to the entity which updates the value - does not await a response
        await context.Entities.SignalEntityAsync(entityId, "Add", 1);
    }
}

JavaScript

const df = require("durable-functions");

module.exports = df.orchestrator(function* (context) {
    const entityId = new df.EntityId("Counter", "myCounter");

    // Two-way call to the entity which returns a value - awaits the response
    const currentValue = yield context.df.callEntity(entityId, "get");
    return currentValue;
});

Poznámka:

JavaScript nepodporuje signalizaci entity z orchestrátoru. Místo toho použijte callEntity.

Python

@myApp.orchestration_trigger(context_name="context")
def orchestrator(context: df.DurableOrchestrationContext):
    entityId = df.EntityId("Counter", "myCounter")
    context.signal_entity(entityId, "add", 3)
    state = yield context.call_entity(entityId, "get")
    return state

PowerShell

PowerShell momentálně nepodporuje funkce entit.

Java

@FunctionName("CounterOrchestration")
public String counterOrchestration(
    @DurableOrchestrationTrigger(name = "ctx") TaskOrchestrationContext ctx) {

    String entityKey = ctx.getInput(String.class);
    EntityInstanceId entityId = new EntityInstanceId("Counter", entityKey);

    // Signal entity operations (fire-and-forget)
    ctx.signalEntity(entityId, "add", 10);
    ctx.signalEntity(entityId, "add", 5);
    ctx.signalEntity(entityId, "subtract", 3);

    // Call entity and wait for result
    int value = ctx.callEntity(entityId, "get", Integer.class).await();

    return "Counter '" + entityKey + "' final value: " + value;
}

Pouze orchestrace může volat entity a získat odpověď, což může být návratová hodnota nebo výjimka. Klientské funkce, které používají vazbu klienta , můžou signalizovat pouze entity.

Orchestratoři mohou přistupovat k entitám pomocí Entities API daného kontextu:

C#

public class CounterOrchestration : TaskOrchestrator<string, int>
{
    public override async Task<int> RunAsync(TaskOrchestrationContext context, string entityKey)
    {
        var entityId = new EntityInstanceId(nameof(Counter), entityKey);

        // Two-way call to the entity which returns a value - awaits the response
        int currentValue = await context.Entities.CallEntityAsync<int>(entityId, nameof(Counter.Get));

        if (currentValue < 10)
        {
            // One-way signal to the entity - does not await a response
            await context.Entities.SignalEntityAsync(entityId, nameof(Counter.Add), 1);
        }

        return currentValue;
    }
}

JavaScript

const counterOrchestration = async function* (ctx, entityKey) {
  const counterId = new EntityInstanceId("Counter", entityKey);

  // Two-way call to the entity which returns a value - awaits the response
  const currentValue = yield* ctx.entities.callEntity(counterId, "get");

  if (currentValue < 10) {
    // One-way signal to the entity - does not await a response
    ctx.entities.signalEntity(counterId, "add", 1);
  }

  return currentValue;
};

Python

def counter_orchestration(ctx: task.OrchestrationContext, entity_key: str):
    entity_id = EntityId("Counter", entity_key)

    # Two-way call to the entity which returns a value
    current_value = yield ctx.call_entity(entity_id, "get")

    if current_value < 10:
        # One-way signal to the entity
        ctx.signal_entity(entity_id, "add", 1)

    return current_value

PowerShell

Podpora PowerShellu pro odolné entity zatím není dostupná. Zkontrolujte budoucí aktualizace.

Java

return ctx -> {
    EntityInstanceId counterId = new EntityInstanceId("Counter", entityKey);

    // Two-way call to the entity which returns a value - awaits the response
    int currentValue = ctx.callEntity(counterId, "get", Integer.class).await();

    if (currentValue < 10) {
        // One-way signal to the entity - does not await a response
        ctx.signalEntity(counterId, "add", 1);
    }

    ctx.complete(currentValue);
};

Pouze orchestrátory můžou volat entity a získat odpověď, což může být návratová hodnota nebo výjimka. Klienti mohou signalizovat pouze entity.

Poznámka:

Volání entity z orchestrátoru se podobá volání aktivity. Hlavní rozdíl spočívá v tom, že entity jsou odolné objekty s adresou (ID entity) a podporují zadání názvu operace. Aktivity jsou bezstavové a nemají koncept operací.

Příklad: Entita signalizuje entitu

Funkce entity může během provádění operace odesílat signály jiným entitám nebo dokonce sama sobě. Například upravte předchozí Counter příklad entity tak, aby při dosažení hodnoty 100 na čítači odeslal signál "dosažení milníku" do monitorovací entity.

C#

V procesu:

   case "add":
        var currentValue = ctx.GetState<int>();
        var amount = ctx.GetInput<int>();
        if (currentValue < 100 && currentValue + amount >= 100)
        {
            ctx.SignalEntity(new EntityId("MonitorEntity", ""), "milestone-reached", ctx.EntityKey);
        }

        ctx.SetState(currentValue + amount);
        break;

Izolovaný pracovní proces:

case "add":
    var currentValue = operation.State.GetState<int>();
    var amount = operation.GetInput<int>();
    if (currentValue < 100 && currentValue + amount >= 100)
    {
        operation.Context.SignalEntity(new EntityInstanceId("MonitorEntity", ""), "milestone-reached", operation.Context.EntityInstanceId);
    }

    operation.State.SetState(currentValue + amount);
    break;

JavaScript

    case "add":
        const amount = context.df.getInput();
        if (currentValue < 100 && currentValue + amount >= 100) {
            const entityId = new df.EntityId("MonitorEntity", "");
            context.df.signalEntity(entityId, "milestone-reached", context.df.instanceId);
        }
        context.df.setState(currentValue + amount);
        break;

Python

Poznámka:

Python nepodporuje signály entity-entit. K signalizaci entit použijte orchestrátor.

PowerShell

PowerShell momentálně nepodporuje funkce entit.

Java

Následující příklad ukazuje signalizaci mezi entitami. Když dojde k velkému vkladu, entita Account signalizuje entitu Audit k zaznamenání transakce.

public class AccountEntity extends AbstractTaskEntity<Integer> {
    private static final int LARGE_TRANSACTION_THRESHOLD = 500;

    public void deposit(int amount) {
        this.state += amount;
        String key = this.context.getId().getKey();

        // Entity signals another entity: notify the audit entity of large deposits
        if (amount >= LARGE_TRANSACTION_THRESHOLD) {
            EntityInstanceId auditEntityId = new EntityInstanceId("Audit", "ledger");
            String message = String.format("Large deposit of %d into account '%s'", amount, key);
            this.context.signalEntity(auditEntityId, "record", message);
        }
    }

    // ... other operations ...

    @Override
    protected Integer initializeState(TaskEntityOperation operation) {
        return 0;
    }

    @Override
    protected Class<Integer> getStateType() {
        return Integer.class;
    }
}

Koordinace entit

Někdy potřebujete koordinovat operace napříč více entitami. Například v bankovní aplikaci mohou entity představovat jednotlivé bankovní účty. Při převodu finančních prostředků z jednoho účtu do druhého je třeba zajistit, aby zdrojový účet má dostatek finančních prostředků. Musíte také aktualizovat oba účty jako jednu konzistentní operaci.

Příklad: Převodní prostředky

Následující příklad kódu přenese prostředky mezi dvěma entitami účtu pomocí funkce orchestrátoru. Ke koordinaci aktualizací entit použijte zámek k vytvoření kritické sekce v orchestraci.

Poznámka:

Pro zjednodušení tento příklad znovu použije dříve definovanou entitu Counter . Ve skutečné aplikaci je lepší definovat podrobnější BankAccount entitu.

C#

Použijte metodu LockAsync k vytvoření kritické části.

// This is a method called by an orchestrator function
public static async Task<bool> TransferFundsAsync(
    string sourceId,
    string destinationId,
    int transferAmount,
    IDurableOrchestrationContext context)
{
    var sourceEntity = new EntityId(nameof(Counter), sourceId);
    var destinationEntity = new EntityId(nameof(Counter), destinationId);

    // Create a critical section to avoid race conditions.
    // No operations can be performed on either the source or
    // destination accounts until the locks are released.
    using (await context.LockAsync(sourceEntity, destinationEntity))
    {
        ICounter sourceProxy =
            context.CreateEntityProxy<ICounter>(sourceEntity);
        ICounter destinationProxy =
            context.CreateEntityProxy<ICounter>(destinationEntity);

        int sourceBalance = await sourceProxy.Get();

        if (sourceBalance >= transferAmount)
        {
            await sourceProxy.Add(-transferAmount);
            await destinationProxy.Add(transferAmount);

            // the transfer succeeded
            return true;
        }
        else
        {
            // the transfer failed due to insufficient funds
            return false;
        }
    }
}

V .NET LockAsync vrací IDisposable. Ukončení to ukončí kritickou sekci. Použijte ho s blokem using , který představuje kritický oddíl.

V předchozím příkladu funkce orchestrátoru přenese prostředky ze zdrojové entity do cílové entity. Metoda LockAsync uzamkne jak entity zdroje, tak cílového účtu. Toto uzamčení zajišťuje, že žádný jiný klient nemůže dotazovat ani měnit stav žádného z účtů, dokud orchestrační logika neopustí kritickou sekci na konci příkazu using . Toto chování brání přečervení zdrojového účtu.

JavaScript

Použijte metodu context.df.lock k vytvoření kritické části.

const df = require("durable-functions");

// This is an orchestrator function
module.exports = df.orchestrator(function* (context) {
    const { sourceId, destinationId, transferAmount } = context.df.getInput();
    const sourceEntity = new df.EntityId("Counter", sourceId);
    const destinationEntity = new df.EntityId("Counter", destinationId);

    // Create a critical section to avoid race conditions.
    // No operations can be performed on either the source or
    // destination accounts until the lock is released.
    const lock = yield context.df.lock(sourceEntity, destinationEntity);
    try {
        const sourceBalance = yield context.df.callEntity(sourceEntity, "get");

        if (sourceBalance >= transferAmount) {
            yield context.df.callEntity(sourceEntity, "add", -transferAmount);
            yield context.df.callEntity(destinationEntity, "add", transferAmount);

            // the transfer succeeded
            return true;
        } else {
            // the transfer failed due to insufficient funds
            return false;
        }
    } finally {
        lock.release();
    }
});

V JavaScriptu context.df.lock vrací DurableLock. Zavolejte release na něj k ukončení kritické části, nebo nechte runtime automaticky uvolnit zámek, když orchestrace skončí.

V předchozím příkladu funkce orchestrátoru přenese prostředky ze zdrojové entity do cílové entity. Metoda lock uzamkne jak entity zdroje, tak cílového účtu. Toto uzamčení zajišťuje, že žádný jiný klient nemůže dotazovat ani měnit stav žádného z účtů, dokud orchestrační logika zámok neuvolní. Toto chování brání přečervení zdrojového účtu.

Python

Poznámka:

Python momentálně nepodporuje kritické části.

PowerShell

Poznámka:

PowerShell momentálně nepodporuje kritické sekce.

Java

Poznámka:

Java momentálně kritické sekce nepodporuje.

Poznámka:

Když orchestrace skončí ( obvykle nebo s chybou), všechny kritické části probíhající implicitně končí a systém uvolní všechny zámky.

Chování kritické sekce

C#

Metoda LockAsync vytvoří kritickou sekci v orchestraci. Tyto kritické části brání ostatním orchestracím v provádění překrývajících se změn v zadané sadě entit. Rozhraní API LockAsync interně odesílá operace "lock" do entit a vrací se po přijetí odpovědi "lock acquired" od každé entity. Zámky i odemknutí jsou integrované operace podporované všemi entitami.

Ostatní klienti nemůžou spouštět operace u entity, když je uzamčená. Toto chování zajišťuje, že entitu může najednou uzamknout pouze jedna instance orchestrace. Pokud se volající pokusí vyvolat operaci na entitě v době, kdy je uzamčena orchestrací, je tato operace umístěna do fronty čekajících operací. Dokud orchestrující proces neuvolní zámek, nezpracují se žádné čekající operace.

Poznámka:

Toto chování se mírně liší od primitiv synchronizace používaných ve většině programovacích jazyků, jako lock je například příkaz v jazyce C#. Například v jazyce C# musí všechna vlákna použít příkaz lock k zajištění správné synchronizace. Entity ale nevyžadují, aby všichni volající explicitně zamkli entitu. Pokud jakýkoli volající zamkne entitu, všechny ostatní operace s touto entitou budou blokovány a zařazeny do fronty za tento zámek.

Zámky na entitách jsou odolné, takže se zachovají i v případě, že se proces provádění recykluje. Systém udržuje zámky jako součást odolného stavu entity.

Na rozdíl od transakcí se kritické sekce automaticky nevrátí ke změnám, když dojde k chybám. Místo toho zapisujte zpracování chyb, například vrácení zpět nebo opakování, například zachycením chyb nebo výjimek. Tato volba návrhu je úmyslná. Automatické vrácení všech efektů orchestrace je obecně obtížné nebo nemožné, protože orchestrace mohou spouštět aktivity a mít externí volání na služby, které nelze vrátit zpět. Pokusy o vrácení zpět mohou také selhat a vyžadovat další zpracování chyb.

JavaScript

Metoda context.df.lock vytvoří kritickou sekci v orchestraci. Tyto kritické části brání ostatním orchestracím v provádění překrývajících se změn v zadané sadě entit. Interně rozhraní lock API odesílá entitám operace „uzamčení“ a po obdržení odpovědi „uzamčení získáno“ od každé entity vrátí DurableLock. Zámky i odemknutí jsou integrované operace podporované všemi entitami.

Poznámka:

context.df.lock API vyžaduje verzi 3.4.0 nebo později durable-functions balíčku npm a verzi 3.13.0 či později Microsoft.Azure.WebJobs.Extensions.DurableTask rozšíření. Dokud nebude verze 3.13.0 dostupná v balíčku rozšíření, instalujte rozšíření ručně.

Podívejte se, kdy jsou k dispozici verze pro rozšířený balíček.

K ukončení kritické sekce zavolejte release u vráceného objektu DurableLock, nebo nechte modul runtime automaticky uvolnit zámek po dokončení orchestrace. Uvolnění zámku hned po skončení kritické práce umožňuje jiným orchestracím jej získat dříve. Použijte context.df.isLocked k ověření, zda je zámek aktuálně držen.

const lock = yield context.df.lock(sourceEntity, destinationEntity);
try {
    yield context.df.callEntity(sourceEntity, "add", -amount);
    yield context.df.callEntity(destinationEntity, "add", amount);
} finally {
    lock.release();
}

Ostatní klienti nemůžou spouštět operace u entity, když je uzamčená. Toto chování zajišťuje, že entitu může najednou uzamknout pouze jedna instance orchestrace. Pokud se volající pokusí vyvolat operaci na entitě v době, kdy je uzamčena orchestrací, je tato operace umístěna do fronty čekajících operací. Dokud orchestrující proces neuvolní zámek, nezpracují se žádné čekající operace.

Poznámka:

Toto chování se mírně liší od synchronizačních primitiv používaných ve většině programovacích jazyků. Entity nevyžadují, aby všichni volající explicitně získali zámek. Pokud jakýkoli volající zamkne entitu, všechny ostatní operace s touto entitou budou blokovány a zařazeny do fronty za tento zámek.

Zámky na entitách jsou odolné, takže se zachovají i v případě, že se proces provádění recykluje. Systém udržuje zámky jako součást odolného stavu entity.

Na rozdíl od transakcí se kritické sekce automaticky nevrátí ke změnám, když dojde k chybám. Místo toho zapište manipulaci s chybami, například při návratu zpět nebo opětovném pokusu, například zachycením chyb. Tato volba návrhu je úmyslná. Automatické vrácení všech efektů orchestrace je obecně obtížné nebo nemožné, protože orchestrace mohou spouštět aktivity a mít externí volání na služby, které nelze vrátit zpět. Pokusy o vrácení zpět mohou také selhat a vyžadovat další zpracování chyb.

Python

Poznámka:

Python momentálně nepodporuje kritické části.

PowerShell

Poznámka:

Kritické sekce nejsou v PowerShellu v současnosti podporovány.

Java

Poznámka:

Java momentálně kritické sekce nepodporuje.

Pravidla kritické sekce

Na rozdíl od nízkoúrovňových uzamykacích primitiv ve většině programovacích jazyků kritické sekce zaručují žádné zablokování. Aby se zabránilo zablokování, systém vynucuje následující omezení:

• Kritické sekce nelze vnořit.
• Suborchestrace nelze vytvářet v kritických částech.
• Volat můžete pouze ty entity, které zamknete v kritických sekcích.
• Nemůžete volat stejnou entitu použitím více paralelních volání v kritických sekcích.
• Entity mimo zámek můžete signalizovat pouze v kritických sekcích.

C#

Pokud porušíte některá z těchto pravidel, runtime vyhodí chybu, například LockingRulesViolationException v .NET. Chybová zpráva vysvětluje, které pravidlo bylo porušeno.

JavaScript

Pokud porušíte některá z těchto pravidel, runtime zobrazí chybu. Chybová zpráva vysvětluje, které pravidlo bylo porušeno.

Python

Poznámka:

Python momentálně nepodporuje kritické části.

PowerShell

Poznámka:

Kritické sekce nejsou v PowerShellu v současnosti podporovány.

Java

Poznámka:

Java momentálně kritické sekce nepodporuje.

Porovnání trvalých entit s virtuálními aktéry

Odolné entity používají mnoho nápadů z modelu aktorů. Pokud znáte aktéry, možná znáte několik konceptů v tomto článku. Odolné entity se podobají virtuálním hercům, označovaným také jako zrnka, z projektu Orleans. Například:

• Trvalé entity adresujete pomocí ID entity.
• Operace odolné entity jsou prováděny sériově, aby se zabránilo závodům.
• Volání nebo signalizace entity ji vytvoří implicitně.
• Modul runtime uvolní entity z paměti, když nejsou spuštěné.

Mezi klíčové rozdíly patří:

• Odolné entity upřednostňují odolnost před latencí, takže nemusí odpovídat aplikacím s přísnými požadavky na latenci.
• Trvalé entity nevysadí časový limit zpráv. Orleans vyprší časový limit zpráv po konfigurovatelném období (ve výchozím nastavení 30 sekund).
• Entity doručují zprávy spolehlivě a v pořadí. Orleans podporuje spolehlivé, seřazené doručování streamovaných zpráv, ale nezaručuje to pro všechny zprávy mezi grainy.
• Orchestrace jsou jediným místem, kde můžete s entitami použít komunikaci typu požadavek-odpověď. Uvnitř entity použijte jednosměrné zasílání zpráv (signalizace), jako je v původním modelu objektu actor.
• Odolné entity nemají deadlock. Orleans se může zablokovat a zablokování přetrvává, dokud zprávy nevyprší.
• Trvalé entity pracují s odolnými orchestracemi a podporují distribuované mechanismy uzamčení.

Další kroky

Přečtěte si příručku pro vývojáře o trvalých entitách v .NET

Informace o centrech úloh

Začínáme se sadami SDK Durable Task