Tartós entitások

Az entitásfüggvények olyan műveleteket határoznak meg, amelyek kis méretű állapotokat, úgynevezett tartós entitásokat olvasnak és frissítenek. A vezénylőfüggvényekhez hasonlóan az entitásfüggvények is egy speciális eseményindító-típust, az entitás-eseményindítót használják. A vezénylőfüggvényekkel ellentétben az entitásfüggvények explicit módon kezelik az entitásállapotokat ahelyett, hogy az állapotot a vezérlőfolyamaton keresztül jelölik. Az entitások segítenek az alkalmazások vertikális felskálázásában azáltal, hogy a munkát számos entitás között osztja el, amelyek mindegyike szerény állapotú.

Az entitások olyan műveleteket határoznak meg, amelyek kis méretű állapotokat, úgynevezett tartós entitásokat olvasnak és frissítenek. A vezénylőkkel ellentétben az entitások explicit módon kezelik az állapotot ahelyett, hogy az állapotot a vezérlési folyamaton keresztül jelölik. Az entitások segítenek az alkalmazások vertikális felskálázásában azáltal, hogy a munkát számos entitás között osztja el, amelyek mindegyike szerény állapotú.

Tartós entitások támogatása

Az entitásfüggvények és a kapcsolódó funkciók Durable Functions 2.0 és újabb verziókban érhetők el.

Programozási nyelv	Tartós entitások támogatása
.NET független	✅
.NET folyamatban	✅
Java	✅
Python	✅
JavaScript	✅
PowerShell	❌

Tartós feladat SDK	Tartós entitások támogatása
.NET független	✅
.NET folyamatban	✅
Java	✅
Python	✅
JavaScript	✅
PowerShell	❌

A tartós entitások általános fogalmai

Az entitások az üzenetek használatával kommunikáló kis szolgáltatásokhoz hasonlóan működnek. Minden entitás egyedi identitással és szükség esetén belső állapotú. Az entitások akkor futtatják a műveleteket, amikor a rendszer kéri. Előfordulhat, hogy egy művelet frissíti az állapotot, meghívja a külső szolgáltatásokat, vagy megvárja a választ. Az entitások a futtatókörnyezet által megbízható üzenetsorokon keresztül küldött üzeneteken keresztül kommunikálnak más entitásokkal, vezénylésekkel és ügyfelekkel.

Az ütközések elkerülése érdekében egyetlen entitás egymás után futtatja a műveleteket egymás után.

Megjegyzés:

Amikor meghív egy entitást, az feldolgozza a hasznos adatokat a befejezésig, majd ütemez egy új végrehajtást, amely új bemenet érkezésekor aktiválódik. Ennek eredményeképpen előfordulhat, hogy az entitás-végrehajtási naplók minden egyes meghívás után további végrehajtást mutatnak. Ez várható.

Entitás azonosítója

Az entitás azonosítójával érhet el egy entitást. Az entitásazonosító egy sztringpár, amely egyedileg azonosít egy entitáspéldányt. A következőkből áll:

• Entitás neve, amely azonosítja az entitás típusát. Például: Counter. Ez a név megegyezik az entitást megvalósító entitásfüggvény nevével. A kis- és nagybetűk nem érzékenyek.
• Entitáskulcs, amely egyedileg azonosítja az entitást az azonos nevű többi entitás között. Például egy GUID.

Például egy Counter entitásfüggvény használható a pontszám online játékban való megtartásához. A játék minden példánya egyedi entitásazonosítóval rendelkezik, például @Counter@Game1 és @Counter@Game2. Egy entitás megcélzásához adja meg az entitás azonosítóját.

Entitásműveletek

Egy entitáson végzett művelet meghívásához adja meg a következőket:

• A cél entitás entitásazonosítója.
• Művelet neve, amely egy sztring, amely meghatározza a végrehajtandó műveletet. Például az Counter entitás támogathatja a add, get, vagy reset műveleteket.
• Művelet bemenete, amely a művelet opcionális paramétere. A művelet például add egy egész számot vesz fel bemenetként.
• Ütemezett idő, amely nem kötelező paraméter a művelet kézbesítési idejének megadásához. Ütemezzen például egy műveletet néhány nappal későbbre.

A műveletek eredményértéket vagy hibaeredményt, például JavaScript-hibát vagy .NET kivételt adhatnak vissza. A hívó orkesztráció megkapja az eredményt vagy a hibát.

A műveletek eredményértéket vagy hibaeredményt adhatnak vissza, például .NET kivételt vagy Python kivételt. A hívó megkapja az eredményt vagy a hibát.

Az entitásművelet emellett létrehozhatja, elolvashatja, frissítheti és törölheti az entitás állapotát. A futtatókörnyezet mindig megőrzi az entitás állapotát a tárolóban.

Entitások definiálása

C#

Két API egyikével definiálhat entitásokat a .NET:

Függvényalapú szintaxis: A függvényalapú szintaxisban minden entitást függvényként kell írnia, és műveleteket kell küldenie az alkalmazásban. Ez a szintaxis jól működik az egyszerű állapotú, kevés művelettel vagy dinamikus műveletkészlettel rendelkező entitások esetében, például az alkalmazás-keretrendszerekben. A karbantartás azonban nehézkes lehet, mert fordításkor nem észlel típushibákat.

Osztályalapú szintaxis: Az osztályalapú szintaxisban .NET osztályok és metódusok entitásai és műveletei. Ez a szintaxis megkönnyíti a kód olvasását, és lehetővé teszi a műveletek biztonságos típusba hívását. Ez egy vékony réteg a függvényalapú szintaxis tetején, így mindkét változatot kombinálhatja ugyanabban az alkalmazásban.

A használt API-k attól függenek, hogy hol futnak a C# függvények. Ajánlott izolált feldolgozói folyamat , de futtatható a gazdafolyamatban is.

Folyamaton belüli függvényalapú példa:

Ez a példa egy egyszerű entitást Counter mutat be, amely tartós függvényként van implementálva. Három olyan műveletet határoz meg,addresetget amelyek egész számot használnak.

[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;
    }
}

További információ: Függvényalapú szintaxis.

Folyamatközi osztályalapú példa:

Ez a példa ugyanazt Counter az entitást mutatja be, amelyet osztályok és metódusok használatával valósítottak meg.

[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>();
}

Ez az entitás az Counter aktuális számláló értékét tartalmazó objektumban tárolja az állapotot. Durable Functions szerializálja és deszerializálja ezt az objektumot a Json.NET könyvtár használatával.

További információ: Entitásosztályok definiálása.

Izolált feldolgozási folyamatfüggvény alapú példa:

Az alábbi példa egy függvényalapú Counter entitást mutat be egy izolált feldolgozófolyamatban. Támogatja add, reset, get, és 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;
    });
}

Izolált munkafolyamat osztály alapú példája:

Az alábbi példa az entitás osztályok és metódusok használatával történő megvalósítását Counter mutatja be.

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);
    }
}

JavaScript

A tartós entitások a 1.3.0 npm-csomag durable-functions verziójától kezdve érhetők el JavaScriptben. Ez a példa a Counter JavaScriptben tartós függvényként implementált entitást mutatja be.

Counter/function.json

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

Számláló/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

Az alábbi kód a Counter entitás, mely egy durable függvényként van megvalósítva Pythonban.

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

Az entitásfüggvények jelenleg nem támogatottak a PowerShellben.

Java

Durable Functions Java (1.9.0-s verzió) támogatja az entitások osztályalapú szintaxissal történő meghatározását. Kiterjesztheti a AbstractTaskEntity<TState> alaposztályt az entitás definiálására.

Az alábbi példa egy Counter entitást mutat be, amely tartós függvényként van implementálva Java.

Entitásosztály:

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;
    }
}

Entitásfüggvény:

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

C#

A Durable Task SDK for .NET osztályalapú szintaxissal támogatja az entitások meghatározását. Az entitás definiálásához implementálhatja az TaskEntity<TState> alaposztályt.

Az alábbi példa egy Counter , a Durable Task SDK használatával implementált entitást mutat be:

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;
}

Az entitás regisztrálása a munkavállalónál:

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

Entitás jelzése vagy meghívása egy orkesztrátorból:

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

A Durable Task SDK for JavaScript/TypeScript osztályalapú szintaxissal támogatja az entitások meghatározását. Kiterjesztheti a TaskEntity<TState> alaposztályt az entitás definiálására.

Az alábbi példa egy Counter , a Durable Task SDK használatával implementált entitást mutat be:

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 };
  }
}

Az entitás regisztrálása a munkavállalónál:

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

Python

A Durable Task SDK for Python függvényalapú szintaxissal támogatja az entitások meghatározását.

Az alábbi példa egy Counter , a Durable Task SDK használatával implementált entitást mutat be:

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)

Az entitás regisztrálása a munkavállalónál:

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

PowerShell

A tartós entitások PowerShell-támogatása még nem érhető el. Tekintse meg a jövőbeli frissítéseket.

Java

A Java-hoz készült Durable Task SDK osztályalapú szintaxissal támogatja az entitások meghatározását. Kiterjesztheti a AbstractTaskEntity<TState> alaposztályt az entitás definiálására.

Az alábbi példa egy Counter , a Durable Task SDK használatával implementált entitást mutat be:

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;
    }
}

Az entitás regisztrálása a munkavállalónál:

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

worker.start();

Entitás jelzése vagy meghívása egy orkesztrátorból:

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);
};

Hozzáférési entitások

Entitások elérése egyirányú vagy kétirányú kommunikációval:

• Az entitás meghívása kétirányú (oda-vissza) kommunikációt használ. Küldjön egy műveleti üzenetet az entitásnak, majd várja meg a válaszüzenetet a folytatás előtt. A válaszüzenet eredményértéket vagy hibát (például JavaScript-hibát vagy .NET kivételt) ad meg.
• Jelző egy entitás egyirányú (eldobható) kommunikációt használ. Küldjön egy műveleti üzenetet, de ne várjon a válaszra. A futtatókörnyezet garantálja a kézbesítést, de a feladó nem tudja megfigyelni az eredményértékeket és a hibákat.

Entitások elérése ügyfélfüggvényekből, vezénylő függvényekből vagy entitásfüggvényekből. Nem minden környezet támogatja mindkét kommunikációs típust:

• Az ügyfélfüggvények támogatják az entitások jelzését és az entitás állapotának olvasását.
• Az Orchestrator funkciók támogatják az entitások jelezését és hívását.
• Az entitásfüggvények támogatják az entitások jelzését.

Entitások elérése egyirányú vagy kétirányú kommunikációval:

• Az entitás meghívása kétirányú (oda-vissza) kommunikációt használ. Küldjön egy műveleti üzenetet az entitásnak, majd várja meg a válaszüzenetet a folytatás előtt. A válaszüzenet eredményértéket vagy hibát ad meg.
• Jelző egy entitás egyirányú (eldobható) kommunikációt használ. Küldjön egy műveleti üzenetet, de ne várjon a válaszra. A futtatókörnyezet garantálja a kézbesítést, de a feladó nem tudja megfigyelni az eredményértékeket és a hibákat.

Az entitások elérése ügyfelektől vagy orkesztrátoroktól. Nem minden környezet támogatja mindkét kommunikációs típust:

• Az ügyfelek támogatják az entitások jelzését és az entitás állapotának olvasását.
• A vezénylők támogatják a jelző és hívó entitásokat.

Az alábbi példák az entitások elérését mutatják be.

Példa: az ügyfél egy entitást jelez

Ha egy egyszerű Azure függvényből, más néven ügyfélfüggvényből szeretne entitásokat elérni, használja a entity ügyfélkötést. Jelen példában egy sor által aktivált függvényt mutatunk be, amely egy entitást jelez az adott kötés használatával.

C#

Megjegyzés:

Az egyszerűség kedvéért az alábbi példák az entitásokhoz való hozzáférés lazán beírt szintaxisát mutatják be. Az entitásokat általában interfészeken keresztül érheti el, mert több típusellenőrzést biztosítanak.

Folyamatban:

Folyamatban:

[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);
}

Izolált munkafolyamat:

[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

Az entitásfüggvények jelenleg nem támogatottak a PowerShellben.

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();
}

A jel kifejezés azt jelenti, hogy az entitás API-meghívása egyirányú és aszinkron. Az ügyfélfüggvények nem tudják, hogy az entitás mikor dolgozza fel a műveletet. Az ügyfélfüggvény nem tudja megfigyelni az eredményértékeket vagy a kivételeket.

Az entitások ügyféloldali eléréséhez használja az DurableTaskClient-t az entitásállapot jelzésére vagy olvasására.

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

A tartós entitások PowerShell-támogatása még nem érhető el. Tekintse meg a jövőbeli frissítéseket.

Java

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

A jel kifejezés azt jelenti, hogy az entitás API-meghívása egyirányú és aszinkron. Az ügyfél nem tudja, mikor dolgozza fel az entitás a műveletet.

Példa: az ügyfél beolvassa az entitás állapotát

Entitásállapot lekérdezése ügyfélfüggvényből:

C#

Folyamatban:

[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);
}

Izolált munkafolyamat:

[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

Az entitásfüggvények jelenleg nem támogatottak a PowerShellben.

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();
}

Az ügyfelek lekérdezhetik egy entitás állapotát:

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

A tartós entitások PowerShell-támogatása még nem érhető el. Tekintse meg a jövőbeli frissítéseket.

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);
}

Az entitásállapot-lekérdezéseket a rendszer elküldi a tartós nyomkövetési tárolóba, és visszaadja az entitás legutóbb megőrzött állapotát. Ez az állapot mindig "véglegesített" állapot, vagyis soha nem ideiglenes köztes állapot, amelyet a művelet végrehajtása során feltételeznek. Ez az állapot azonban elavult lehet az entitás memóriabeli állapotához képest. Az entitás memóriabeli állapotát csak vezénylések olvashatják el a következő szakaszban leírtak szerint.

Példa: vezénylési jelek és entitás meghívása

Az Orchestrator-függvények az API-kkal férhetnek hozzá az entitásokhoz az orchestration trigger kötésén keresztül. Az alábbi példakód egy entitás meghívását és jelzését végző vezénylő függvényt Counter mutat be.

C#

Folyamatban:

[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);
    }
}

Izolált munkafolyamat:

[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;
});

Megjegyzés:

A JavaScript nem támogatja az entitás vezénylőből történő jelzését. A callEntity használható helyette.

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

Az entitásfüggvények jelenleg nem támogatottak a PowerShellben.

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;
}

Csak orkesztációk hívhatnak entitásokat, és kaphatnak választ, ami lehet visszatérési érték vagy kivétel. Az ügyfélkötést használó ügyfélfüggvények csak entitásokat jelezhetnek.

Az vezénylők a környezet Entitások API-jával férhetnek hozzá az entitásokhoz:

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

A tartós entitások PowerShell-támogatása még nem érhető el. Tekintse meg a jövőbeli frissítéseket.

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);
};

Csak a vezénylők hívhatnak meg entitásokat, és kaphatnak választ, ami lehet visszatérési érték vagy kivétel. Az ügyfelek csak entitásokat jelezhetnek.

Megjegyzés:

Egy entitás meghívása egy orchestratortól hasonló egy tevékenység meghívásához. A fő különbség az, hogy az entitások olyan tartós objektumok, amelyek címmel (entitásazonosítóval) vannak elnevezve, és támogatják a művelet nevét. A tevékenységek állapot nélküliek, és nem rendelkeznek a műveletek koncepciójával.

Példa: entitás jelzi az entitást

Az entitásfüggvények jeleket küldhetnek más entitásoknak vagy akár önmagának is, miközben egy műveletet hajtanak végre. Módosítsa például az előző Counter entitás példáját úgy, hogy "mérföldkő-elhagyás" jelet küldjön egy monitorozó entitásnak, amikor a számláló eléri a 100-at.

C#

Folyamatban:

   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;

Izolált munkafolyamat:

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

Megjegyzés:

Python nem támogatja az entitások közötti jeleket. Használjon orkesztrátort az entitásoknak való jelzéshez.

PowerShell

Az entitásfüggvények jelenleg nem támogatottak a PowerShellben.

Java

Az alábbi példa az entitások közötti jelzést mutatja be. Nagy összegű befizetés esetén az entitás jelzi az AccountAudit entitásnak a tranzakció rögzítését.

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;
    }
}

Entitáskoordináció

Néha több entitás műveleteinek koordinálására van szükség. Egy banki alkalmazásban például az entitások egyéni bankszámlákat jelölhetnek. Amikor pénzt utal át egyik fiókból a másikba, meg kell győződnie arról, hogy a forrásfiók rendelkezik elegendő pénzeszközzel. Mindkét fiókot egy konzisztens műveletként kell frissítenie.

Példa: Átutalási alapok (C#)

Az alábbi példakód egy vezénylő függvény használatával két számlaentitás között utal át pénzt. Az entitásfrissítések koordinálásához a LockAsync metódussal hozzon létre egy kritikus szakaszt a vezénylésben.

Megjegyzés:

Az egyszerűség kedvéért ez a példa újra felhasználja a Counter korábban definiált entitást. Egy valós alkalmazásban jobb, ha részletesebb entitást BankAccount definiál.

// 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;
        }
    }
}

A .NET-ben LockAsyncIDisposable-t ad vissza. A törlés véget vet a kritikus szakasznak. Használjon blokkot using a kritikus szakasz ábrázolásához.

Az előző példában egy vezénylő függvény pénzösszegeket ad át egy forrás entitásból egy cél entitásba. A LockAsync metódus zárolta a forrás- és célfiók-entitásokat is. Ez a zárolás biztosította, hogy egyetlen másik ügyfél sem tudta lekérdezni vagy módosítani egyik fiók állapotát sem, amíg a vezénylési logika ki nem lépett a kritikus szakaszból az using utasítás végén. Ez a működés megakadályozza a forrásszámlán a túlköltekezést.

Megjegyzés:

Amikor egy vezénylés rendes módon vagy hibával ér véget, a folyamatban lévő kritikus szakaszok implicit módon érnek véget, és a rendszer felold minden zárolást.

Kritikus szakasz viselkedése

A LockAsync metódus kritikus szakaszt hoz létre egy orchestrationban. Ezek a kritikus szakaszok megakadályozzák, hogy más vezénylések egymást átfedő módosításokat hajtsanak végre egy adott entitáskészleten. Az LockAsync API belsőleg "zárolási" műveleteket küld az entitásoknak, és azt követően ad vissza, hogy "zárolt" választ kap az egyes entitásoktól. A zárolás és a zárolás feloldása az összes entitás által támogatott beépített műveletek.

Más ügyfelek nem futtathatnak műveleteket egy entitáson, amíg zárolva van. Ez a viselkedés biztosítja, hogy egyszerre csak egy vezérlési példány zárolhasson egy entitást. Ha egy hívó megpróbál meghívni egy műveletet egy entitáson, miközben egy vezénylés zárolja, a művelet függőben lévő műveleti üzenetsorba kerül. A függőben lévő műveletek feldolgozása csak azután történik, hogy az irányítómű feloldja a zárolását.

Megjegyzés:

Ez a viselkedés kissé eltér a legtöbb programozási nyelvben használt szinkronizálási primitívektől, például a lock C# utasításától. A C#-ban például minden szálnak az utasítást kell használnia a lock megfelelő szinkronizálás biztosításához. Az entitások azonban nem követelik meg, hogy minden hívó explicit módon zároljon egy entitást. Ha bármely hívó lezár egy entitást, az azon az entitáson végzett összes többi művelet blokkolva lesz és várólistára kerül a lezárás mögött.

Az entitások zárolásai tartósak, így akkor is megmaradnak, ha a végrehajtási folyamatot újrafeldolgozzák. A rendszer egy entitás tartós állapotának részeként fenntartja a zárolásokat.

A tranzakcióktól eltérően a kritikus szakaszok nem hajtanak végre automatikusan módosításokat hibák esetén. Ehelyett írjon hibakezelést, például visszaállítást vagy újrapróbálkozást, például hibák vagy kivételek befogásával. Ez a kialakítási döntés szándékos. A vezénylés minden hatásának automatikus visszaállítása általában nehéz vagy lehetetlen, mert a vezénylések tevékenységeket futtathatnak, és olyan külső szolgáltatásokhoz fordulhatnak, amelyek nem állíthatók vissza. A visszaállítási kísérletek szintén sikertelenek lehetnek, és további hibakezelést igényelnek.

Kritikus szakaszszabályok

A legtöbb programozási nyelvben az alacsony szintű zárolási primitívekkel ellentétben a kritikus szakaszok garantáltan nem holtpontra kerülnek. A holtpontok elkerülése érdekében a következő korlátozásokat kényszerítjük ki:

• A kritikus szakaszok nem ágyazhatók be.
• A kritikus szakaszok nem hozhatnak létre al-orkesztációkat.
• A kritikus szakaszok csak a zárolt entitásokat hívhatják meg.
• A kritikus szakaszok nem hívhatják meg ugyanazt az entitást több párhuzamos hívással.
• A kritikus kódszakaszok csak a zárolási csoporton kívüli entitásokat jelezhetik.

A szabályok bármilyen megsértése futásidejű hibát okoz, például LockingRulesViolationException .NET, amely egy üzenetet tartalmaz, amely ismerteti, hogy mi volt a szabály megszegve.

Tartós entitások összehasonlítása virtuális szereplőkkel

A tartós entitások számos ötletet használnak az aktormodellből. Ha ismeri a színészeket, ebben a cikkben számos fogalmat ismerhet fel. A tartós entitások hasonlóak az Orleans-projektből származó virtuális szereplőkhöz, más néven szemcsékhez. Például:

• A tartós entitások kezelése entitásazonosító használatával történik.
• A tartós entitásműveletek sorozatosan futnak a versenyfeltételek elkerülése érdekében.
• Az entitás meghívása vagy jelezése automatikusan létrehozza.
• A futtatókörnyezet eltávolítja az entitásokat a memóriából, ha nem futtatnak műveleteket.

A főbb különbségek a következők:

• A tartós entitások előnyben részesítik a tartósságot a késéssel szemben, ezért előfordulhat, hogy nem felelnek meg a szigorú késési követelményekkel rendelkező alkalmazásoknak.
• A tartós entitások nem időtúllépést hajtanak végre az üzeneteken. Orleans az üzeneteknél időtúllépést állít be egy konfigurálható időszak után (ez alapértelmezés szerint 30 másodperc).
• Az entitások megbízhatóan és sorrendben kézbesítik az üzeneteket. Az Orleans támogatja a megbízható, rendezett kézbesítést a folyamüzenetekhez, de nem garantálja, hogy ez az összes üzenet esetében érvényes a gránumok között.
• Az orchestrációk az egyetlen hely, ahol csak kérés-válasz viszonyban használhatók az entitások. Egy entitáson belül használjon egyirányú üzenetkezelést (jelzést), mint az eredeti aktormodellben.
• A tartós entitások nem patthelyzetben maradnak. Az Orleans holtpontba kerülhet, és ezek a holtpontok fennmaradnak mindaddig, amíg az üzenetek időt nem lépnek.
• A tartós entitások tartós vezénylésekkel működnek, és támogatják az elosztott zárolási mechanizmusokat.

Következő lépések

Olvassa el a .NET tartós entitások fejlesztői útmutatóját

Tudnivalók a tevékenységközpontokról

A Durable Task SDK-k használatának első lépései