Merge pull request #99519 from cgillum/cgillum-edits

PRMerger9 · web-flow · commit d7c469c9828b · 2019-12-19T23:13:38.000-08:00
Update reference docs for Durable v2.1.0
diff --git a/articles/azure-functions/durable/durable-functions-bindings.md b/articles/azure-functions/durable/durable-functions-bindings.md
@@ -2,7 +2,7 @@
 title: Bindings for Durable Functions - Azure
 description: How to use triggers and bindings for the Durable Functions extension for Azure Functions.
 ms.topic: conceptual
-ms.date: 11/02/2019
+ms.date: 12/17/2019
 ms.author: azfuncdf
 ---
 
@@ -393,7 +393,7 @@ Every entity function has a parameter type of `IDurableEntityContext`, which has
 * **DeleteState()**: deletes the state of the entity. 
 * **GetInput\<TInput>()**: gets the input for the current operation. The `TInput` type parameter must be a primitive or JSON-serializeable type.
 * **Return(arg)**: returns a value to the orchestration that called the operation. The `arg` parameter must be a primitive or JSON-serializeable object.
-* **SignalEntity(EntityId, operation, input)**: sends a one-way message to an entity. The `operation` parameter must be a non-null string, and the `input` parameter must be a primitive or JSON-serializeable object.
+* **SignalEntity(EntityId, scheduledTimeUtc, operation, input)**: sends a one-way message to an entity. The `operation` parameter must be a non-null string, the optional `scheduledTimeUtc` must be a UTC datetime at which to invoke the operation, and the `input` parameter must be a primitive or JSON-serializeable object.
 * **CreateNewOrchestration(orchestratorFunctionName, input)**: starts a new orchestration. The `input` parameter must be a primitive or JSON-serializeable object.
 
 The `IDurableEntityContext` object passed to the entity function can be accessed using the `Entity.Current` async-local property. This approach is convenient when using the class-based programming model.
@@ -530,6 +530,7 @@ In .NET functions, you typically bind to `IDurableEntityClient`, which gives you
 
 * **ReadEntityStateAsync\<T>**: reads the state of an entity. It returns a response that indicates whether the target entity exists, and if so, what its state is.
 * **SignalEntityAsync**: sends a one-way message to an entity, and waits for it to be enqueued.
+* **ListEntitiesAsync**: queries for the state of multiple entities. Entities can be queried by *name* and *last operation time*.
 
 There is no need to create the target entity before sending a signal - the entity state can be created from within the entity function that handles the signal.
 
diff --git a/articles/azure-functions/durable/durable-functions-entities.md b/articles/azure-functions/durable/durable-functions-entities.md
@@ -3,7 +3,7 @@ title: Durable entities - Azure Functions
 description: Learn what durable entities are and how to use them in the Durable Functions extension for Azure Functions.
 author: cgillum
 ms.topic: overview
-ms.date: 11/02/2019
+ms.date: 12/17/2019
 ms.author: azfuncdf
 #Customer intent: As a developer, I want to learn what durable entities are and how to use them to solve distributed, stateful problems in my applications.
 ---
@@ -37,6 +37,7 @@ To invoke an operation on an entity, specify the:
 * **Entity ID** of the target entity.
 * **Operation name**, which is a string that specifies the operation to perform. For example, the `Counter` entity could support `add`, `get`, or `reset` operations.
 * **Operation input**, which is an optional input parameter for the operation. For example, the add operation can take an integer amount as the input.
+* **Scheduled time*, which is an optional parameter for specifying the delivery time of the operation. For example, an operation can be reliably scheduled to run several days in the future.
 
 Operations can return a result value or an error result, such as a JavaScript error or a .NET exception. This result or error can be observed by orchestrations that called the operation.
 
diff --git a/articles/azure-functions/durable/durable-functions-http-api.md b/articles/azure-functions/durable/durable-functions-http-api.md
@@ -3,7 +3,7 @@ title: HTTP APIs in Durable Functions - Azure Functions
 description: Learn how to implement HTTP APIs in the Durable Functions extension for Azure Functions.
 author: cgillum
 ms.topic: conceptual
-ms.date: 09/07/2019
+ms.date: 12/17/2019
 ms.author: azfuncdf
 ---
 
@@ -615,7 +615,7 @@ Sends a one-way operation message to a [Durable Entity](durable-functions-types-
 The HTTP request is formatted as follows (multiple lines are shown for clarity):
 
 ```http
-POST /runtime/webhooks/durabletask/entities/{entityType}/{entityKey}
+POST /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}
@@ -626,8 +626,8 @@ Request parameters for this API include the default set mentioned previously as
 
 | Field             | Parameter type  | Description |
 |-------------------|-----------------|-------------|
-| **`entityType`**  | URL             | The type of the entity. |
-| **`entityKey`**   | URL             | The unique name of the entity. |
+| **`entityName`**  | URL             | The name (type) of the entity. |
+| **`entityKey`**   | URL             | The key (unique ID) of the entity. |
 | **`op`**          | Query string    | Optional. The name of the user-defined operation to invoke. |
 | **`{content}`**   | Request content | The JSON-formatted event payload. |
 
@@ -640,17 +640,20 @@ Content-Type: application/json
 5
 ```
 
+> [!NOTE]
+> By default with [class-based entities in .NET](durable-functions-dotnet-entities.md#defining-entity-classes), specifying the `op` value of `delete` will delete the state of an entity. If the entity defines an operation named `delete`, however, that user-defined operation will be invoked instead.
+
 ### Response
 
 This operation has several possible responses:
 
 * **HTTP 202 (Accepted)**: The signal operation was accepted for asynchronous processing.
 * **HTTP 400 (Bad request)**: The request content was not of type `application/json`, was not valid JSON, or had an invalid `entityKey` value.
-* **HTTP 404 (Not Found)**: The specified `entityType` was not found.
+* **HTTP 404 (Not Found)**: The specified `entityName` was not found.
 
 A successful HTTP request does not contain any content in the response. A failed HTTP request may contain JSON-formatted error information in the response content.
 
-## Query entity
+## Get entity
 
 Gets the state of the specified entity.
 
@@ -659,7 +662,7 @@ Gets the state of the specified entity.
 The HTTP request is formatted as follows (multiple lines are shown for clarity):
 
 ```http
-GET /runtime/webhooks/durabletask/entities/{entityType}/{entityKey}
+GET /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}
@@ -689,6 +692,100 @@ If the `Counter` entity simply contained a number of steps saved in a `currentVa
 }
 ```
 
+## List entities
+
+You can query for multiple entities by the entity name or by the last operation date.
+
+### Request
+
+The HTTP request is formatted as follows (multiple lines are shown for clarity):
+
+```http
+GET /runtime/webhooks/durabletask/entities/{entityName}
+    ?taskHub={taskHub}
+    &connection={connectionName}
+    &code={systemKey}
+    &lastOperationTimeFrom={timestamp}
+    &lastOperationTimeTo={timestamp}
+    &fetchState=[true|false]
+    &top={integer}
+```
+
+Request parameters for this API include the default set mentioned previously as well as the following unique parameters:
+
+| Field                       | Parameter type  | Description |
+|-----------------------------|-----------------|-------------|
+| **`entityName`**            | URL             | Optional. When specified, filters the list of returned entities by their entity name (case-insensitive). |
+| **`fetchState`**            | Query string    | Optional parameter. If set to `true`, the entity state will be included in the response payload. |
+| **`lastOperationTimeFrom`** | Query string    | Optional parameter. When specified, filters the list of returned entities that processed operations after the given ISO8601 timestamp. |
+| **`lastOperationTimeTo`**   | Query string    | Optional parameter. When specified, filters the list of returned entities that processed operations  before the given ISO8601 timestamp. |
+| **`top`**                   | Query string    | Optional parameter. When specified, limits the number of entities returned by the query. |
+
+
+### Response
+
+A successful HTTP 200 response contains a JSON-serialized array of entities and optionally the state of each entity.
+
+By default the operation returns the first 100 entities that match the query criteria. The caller can specify a query string parameter value for `top` to return a different maximum number of results. If more results exist beyond what is returned, a continuation token is also returned in the response header. The name of the header is `x-ms-continuation-token`.
+
+If you set continuation token value in the next request header, you can get the next page of results. This name of the request header is also `x-ms-continuation-token`.
+
+### Example - list all entities
+
+The following example HTTP request lists all entities in the task hub:
+
+```http
+GET /runtime/webhooks/durabletask/entities
+```
+
+The response JSON may look like the following (formatted for readability):
+
+```json
+[
+    {
+        "entityId": { "key": "cats", "name": "counter" },
+        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
+    },
+    {
+        "entityId": { "key": "dogs", "name": "counter" },
+        "lastOperationTime": "2019-12-18T21:46:01.9477382Z"
+    },
+    {
+        "entityId": { "key": "mice", "name": "counter" },
+        "lastOperationTime": "2019-12-18T21:46:15.4626159Z"
+    },
+    {
+        "entityId": { "key": "radio", "name": "device" },
+        "lastOperationTime": "2019-12-18T21:46:18.2616154Z"
+    },
+]
+```
+
+### Example - filtering the list of entities
+
+The following example HTTP request lists just the first two entities of type `counter` and also fetches their state:
+
+```http
+GET /runtime/webhooks/durabletask/entities/counter?top=2&fetchState=true
+```
+
+The response JSON may look like the following (formatted for readability):
+
+```json
+[
+    {
+        "entityId": { "key": "cats", "name": "counter" },
+        "lastOperationTime": "2019-12-18T21:45:44.6326361Z",
+        "state": { "value": 9 }
+    },
+    {
+        "entityId": { "key": "dogs", "name": "counter" },
+        "lastOperationTime": "2019-12-18T21:46:01.9477382Z",
+        "state": { "value": 10 }
+    }
+]
+```
+
 ## Next steps
 
 > [!div class="nextstepaction"]
diff --git a/articles/azure-functions/durable/durable-functions-http-features.md b/articles/azure-functions/durable/durable-functions-http-features.md
@@ -27,7 +27,8 @@ The following built-in HTTP APIs are supported.
 * [Send an external event to an orchestration](durable-functions-http-api.md#raise-event)
 * [Purge orchestration history](durable-functions-http-api.md#purge-single-instance-history)
 * [Send an operation event to an entity](durable-functions-http-api.md#signal-entity)
-* [Query the state of an entity](durable-functions-http-api.md#query-entity)
+* [Get the state of an entity](durable-functions-http-api.md#get-entity)
+* [Query the list of entities](durable-functions-http-api.md#list-entities)
 
 See the [HTTP APIs article](durable-functions-http-api.md) for a full description of all the built-in HTTP APIs exposed by the Durable Functions extension.
 
diff --git a/includes/functions-host-json-durabletask.md b/includes/functions-host-json-durabletask.md
@@ -47,14 +47,15 @@ Configuration settings for [Durable Functions](../articles/azure-functions/durab
   "durableTask": {
     "hubName": "MyTaskHub",
     "storageProvider": {
+      "connectionStringName": "AzureWebJobsStorage",
       "controlQueueBatchSize": 32,
-      "partitionCount": 4,
+      "controlQueueBufferThreshold": 256,
       "controlQueueVisibilityTimeout": "00:05:00",
-      "workItemQueueVisibilityTimeout": "00:05:00",
       "maxQueuePollingInterval": "00:00:30",
-      "connectionStringName": "AzureWebJobsStorage",
+      "partitionCount": 4,
       "trackingStoreConnectionStringName": "TrackingStorage",
-      "trackingStoreNamePrefix": "DurableTask"
+      "trackingStoreNamePrefix": "DurableTask",
+      "workItemQueueVisibilityTimeout": "00:05:00",
     },
     "tracing": {
       "traceInputsAndOutputs": false,
@@ -77,7 +78,8 @@ Configuration settings for [Durable Functions](../articles/azure-functions/durab
     "maxConcurrentActivityFunctions": 10,
     "maxConcurrentOrchestratorFunctions": 10,
     "extendedSessionsEnabled": false,
-    "extendedSessionIdleTimeoutInSeconds": 30
+    "extendedSessionIdleTimeoutInSeconds": 30,
+    "useGracefulShutdown": false
   }
 }
 ```
@@ -88,6 +90,7 @@ Task hub names must start with a letter and consist of only letters and numbers.
 |---------|---------|---------|
 |hubName|DurableFunctionsHub|Alternate [task hub](../articles/azure-functions/durable-functions-task-hubs.md) names can be used to isolate multiple Durable Functions applications from each other, even if they're using the same storage backend.|
 |controlQueueBatchSize|32|The number of messages to pull from the control queue at a time.|
+|controlQueueBufferThreshold|256|The number of control queue messages that can be buffered in memory at a time, at which point the dispatcher will wait before dequeuing any additional messages.|
 |partitionCount |4|The partition count for the control queue. May be a positive integer between 1 and 16.|
 |controlQueueVisibilityTimeout |5 minutes|The visibility timeout of dequeued control queue messages.|
 |workItemQueueVisibilityTimeout |5 minutes|The visibility timeout of dequeued work item  queue messages.|
@@ -104,5 +107,6 @@ Task hub names must start with a letter and consist of only letters and numbers.
 |eventGridPublishRetryCount|0|The number of times to retry if publishing to the Event Grid Topic fails.|
 |eventGridPublishRetryInterval|5 minutes|The Event Grid publishes retry interval in the *hh:mm:ss* format.|
 |eventGridPublishEventTypes||A list of event types to publish to Event Grid. If not specified, all event types will be published. Allowed values include `Started`, `Completed`, `Failed`, `Terminated`.|
+|useGracefulShutdown|false|(Preview) Enable gracefully shutting down to reduce the chance of host shutdowns failing in-process function executions.|
 
 Many of these settings are for optimizing performance. For more information, see [Performance and scale](../articles/azure-functions/durable-functions-perf-and-scale.md).
