Référence sur l'API HTTP

  • Article

L’extension Durable Functions expose un ensemble d’API HTTP intégrées qui peuvent être utilisées pour effectuer des tâches de gestion sur des orchestrations, des entités et des hubs de tâches. Ces API HTTP sont des webhooks d’extensibilité qui sont autorisés par l’hôte Azure Functions mais gérés directement par l’extension Durable Functions.

L’URL de base pour les API mentionnées dans cet article est identique à celle de votre application de fonction. Quand vous développez localement à l’aide d’Azure Functions Core Tools, l’URL de base est généralement http://localhost:7071. Dans le service hébergé Azure Functions, l’URL de base est généralement https://{appName}.azurewebsites.net. Les noms d’hôte personnalisés sont également pris en charge s’ils sont configurés sur votre application App Service.

Toutes les API HTTP implémentées par l’extension requièrent les paramètres suivants. Le type de données de tous les paramètres est string.

Paramètre Type de paramètre Description
taskHub Chaîne de requête Le nom du hub de tâches. S’il n’est pas spécifié, le nom de hub de tâches de l’application de fonction en cours est supposé.
connection Chaîne de requête Le nom du paramètre d’application de connexion pour le fournisseur de stockage principal. Si elle n’est pas spécifiée, la configuration de connexion par défaut pour l’application de la fonction est supposée.
systemKey Chaîne de requête La clé d’autorisation requise pour appeler l’API.

systemKey est une clé d’autorisation automatiquement générée par l’hôte Azure Functions. Elle accorde l’accès aux API de l’extension Tâche durable et peut être gérée de la même façon que les autres clés d’accès Azure Functions. Vous pouvez générer des URL qui contiennent les valeurs de chaîne de requête taskHub, connection et systemKey correctes à l’aide des API de liaison du client d’orchestration, telles que les API CreateCheckStatusResponse et CreateHttpManagementPayload dans .NET, les API createCheckStatusResponse et createHttpManagementPayload dans JavaScript, etc.

Les quelques sections suivantes présentent les API HTTP spécifiques prises en charge par l’extension et fournissent des exemples d’utilisation.

Démarrer l’orchestration

Démarre l’exécution d’une nouvelle instance de la fonction d’orchestrateur spécifiée.

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

POST /admin/extensions/DurableTaskExtension/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

POST /runtime/webhooks/durabletask/orchestrators/{functionName}/{instanceId?}
     ?taskHub={taskHub}
     &connection={connectionName}
     &code={systemKey}

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
functionName URL Nom de la fonction d’orchestrateur à démarrer.
instanceId URL Paramètre facultatif. L’ID de l’instance d’orchestration. S’il n’est pas spécifié, la fonction d’orchestrateur démarre avec un ID d’instance aléatoire.
{content} Contenu de la demande Optionnel. Entrée de la fonction d’orchestrateur au format JSON.

response

Plusieurs valeurs de code d’état possibles peuvent être retournées.

  • HTTP 202 (Accepté) : La fonction d’orchestrateur spécifiée a été planifiée pour commencer à s’exécuter. L’en-tête de réponse Location contient une URL pour interroger l’état de l’orchestration.
  • HTTP 400 (Requête incorrecte) : La fonction d’orchestrateur spécifiée n’existe pas, l’ID d’instance spécifié n’était pas valide ou le contenu de la requête n’était pas un contenu JSON valide.

Voici un exemple de demande qui démarre une fonction d’orchestrateur RestartVMs et inclut la charge utile d’objet JSON :

POST /runtime/webhooks/durabletask/orchestrators/RestartVMs?code=XXX
Content-Type: application/json
Content-Length: 83

{
    "resourceGroup": "myRG",
    "subscriptionId": "111deb5d-09df-4604-992e-a968345530a9"
}

La charge utile de réponse pour les cas HTTP 202 est un objet JSON avec les champs suivants :

Champ Description
id L’ID de l’instance d’orchestration.
statusQueryGetUri L’URL de l’état de l’instance d’orchestration.
sendEventPostUri L’URL « Raise event » de l’instance d’orchestration.
terminatePostUri L’URL « d’arrêt » de l’instance d’orchestration.
purgeHistoryDeleteUri URL de « purge de l’historique » de l’instance d’orchestration.
rewindPostUri (préversion) URL de « rembobinage » de l’instance d’orchestration.
suspendPostUri URL de « suspension » de l’instance de l’orchestration.
resumePostUri URL de « reprise » de l’instance de l’orchestration.

Le type de données de tous les champs est string.

Voici un exemple de charge utile de réponse pour une instance d’orchestration avec l’ID abc123 (mis en forme pour une meilleure lisibilité) :

{
    "id": "abc123",
    "purgeHistoryDeleteUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "sendEventPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/raiseEvent/{eventName}?code=XXX",
    "statusQueryGetUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123?code=XXX",
    "terminatePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/terminate?reason={text}&code=XXX",
    "suspendPostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/suspend?reason={text}&code=XXX",
    "resumePostUri": "http://localhost:7071/runtime/webhooks/durabletask/instances/abc123/resume?reason={text}&code=XXX"
}

La réponse HTTP est destinée à être compatible avec le modèle d’interrogation de consommateur. Elle comprend également les en-têtes de réponse notables suivants :

  • Location : URL du point de terminaison de l’état. Cette URL contient la même valeur que le champ statusQueryGetUri.
  • Retry-After : Nombre de secondes à attendre entre les opérations d’interrogation. La valeur par défaut est 10.

Pour plus d’informations sur le modèle d’interrogation HTTP asynchrone, consultez la documentation sur le suivi des opérations asynchrones HTTP.

Obtenir l’état de l’instance

Obtient l'état d'une instance d’orchestration spécifiée.

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

GET /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

GET /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &showHistory=[true|false]
    &showHistoryOutput=[true|false]
    &showInput=[true|false]
    &returnInternalServerErrorOnFailure=[true|false]

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
instanceId URL L’ID de l’instance d’orchestration.
showInput Chaîne de requête Paramètre facultatif. Si la valeur est définie sur false, la fonction n’est pas incluse dans la charge utile de la réponse.
showHistory Chaîne de requête Paramètre facultatif. Si la valeur est définie sur true, l’historique d’exécution de l’orchestration est inclus dans la charge utile de réponse.
showHistoryOutput Chaîne de requête Paramètre facultatif. Si la valeur est définie sur true, les sorties de la fonction sont incluses dans l’historique d’exécution de l’orchestration.
createdTimeFrom Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances retournées qui ont été créées pendant ou après l’horodatage ISO8601 donné.
createdTimeTo Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances retournées qui ont été créées pendant ou avant l’horodatage ISO8601 donné.
runtimeStatus Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances retournées selon leur état d’exécution. Pour obtenir la liste des valeurs d’état d’exécution possibles, consultez l’article Interrogation des instances.
returnInternalServerErrorOnFailure Chaîne de requête Paramètre facultatif. Si la valeur est true, cette API renvoie une réponse HTTP 500 au lieu de 200 si l’instance est dans un état d’échec. Ce paramètre est destiné aux scénarios d’interrogation d’état automatisés.

response

Plusieurs valeurs de code d’état possibles peuvent être retournées.

  • HTTP 200 (OK) : l’instance spécifiée est dans un état terminé ou d’échec.
  • HTTP 202 (acceptée) : l’instance spécifiée est en cours d’exécution.
  • HTTP 400 (Bad Request) : l’instance spécifiée a échoué ou a été arrêtée.
  • HTTP 404 (Not Found) : l’instance spécifiée n’existe pas ou n’a pas démarré.
  • HTTP 500 (erreur de serveur interne) : retourné uniquement lorsque returnInternalServerErrorOnFailure a la valeur true et que l’instance spécifiée a échoué avec une exception non gérée.

La charge utile de réponse pour les cas HTTP 200 et HTTP 202 est un objet JSON avec les champs suivants :

Champ Type de données Description
runtimeStatus string L’état d’exécution de l’instance. Les valeurs sont Running, Pending, Failed, Canceled, Terminated, Completed et Suspended.
input JSON Les données JSON utilisées pour initialiser l’instance. Ce champ est null si le paramètre de chaîne de requête showInput est défini sur false.
customStatus JSON Données JSON utilisées pour l’état d’orchestration personnalisé. Ce champ est null s’il n’est pas défini.
output JSON La sortie JSON de l’instance. Ce champ est null si l’instance n’est pas dans un état terminé.
createdTime string Heure à laquelle l’instance a été créée. Utilise la notation étendue ISO 8601.
lastUpdatedTime string Heure du dernier état persistant de l’instance. Utilise la notation étendue ISO 8601.
historyEvents JSON Tableau JSON contenant l’historique d’exécution de l’orchestration. Ce champ est null, sauf si le paramètre de chaîne de requête showHistory a la valeur true.

Voici un exemple de charge utile de réponse incluant l’historique et les sorties de l’activité d’exécution d’orchestration (mis en forme pour une meilleure lisibilité) :

{
  "createdTime": "2018-02-28T05:18:49Z",
  "historyEvents": [
      {
          "EventType": "ExecutionStarted",
          "FunctionName": "E1_HelloSequence",
          "Timestamp": "2018-02-28T05:18:49.3452372Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Tokyo!",
          "ScheduledTime": "2018-02-28T05:18:51.3939873Z",
          "Timestamp": "2018-02-28T05:18:52.2895622Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello Seattle!",
          "ScheduledTime": "2018-02-28T05:18:52.8755705Z",
          "Timestamp": "2018-02-28T05:18:53.1765771Z"
      },
      {
          "EventType": "TaskCompleted",
          "FunctionName": "E1_SayHello",
          "Result": "Hello London!",
          "ScheduledTime": "2018-02-28T05:18:53.5170791Z",
          "Timestamp": "2018-02-28T05:18:53.891081Z"
      },
      {
          "EventType": "ExecutionCompleted",
          "OrchestrationStatus": "Completed",
          "Result": [
              "Hello Tokyo!",
              "Hello Seattle!",
              "Hello London!"
          ],
          "Timestamp": "2018-02-28T05:18:54.3660895Z"
      }
  ],
  "input": null,
  "customStatus": { "nextActions": ["A", "B", "C"], "foo": 2 },
  "lastUpdatedTime": "2018-02-28T05:18:54Z",
  "output": [
      "Hello Tokyo!",
      "Hello Seattle!",
      "Hello London!"
  ],
  "runtimeStatus": "Completed"
}

La réponse HTTP 202 inclut également un en-tête de réponse Location qui fait référence à la même URL que le champ statusQueryGetUri mentionné précédemment.

Obtenir l’état de toutes les instances

Vous pouvez également interroger l’état de toutes les instances en supprimant l’élément instanceId de la demande « Obtenir l’état de l’instance ». Dans le cas présent, les paramètres de base sont les mêmes que ceux de « Obtenir l’état de l’instance ». Les paramètres de chaîne de requête dédiés au filtrage sont également pris en charge.

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

GET /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

GET /runtime/webhooks/durableTask/instances?
    taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}
    &instanceIdPrefix={prefix}
    &showInput=[true|false]
    &top={integer}

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
showInput Chaîne de requête Paramètre facultatif. Si la valeur est définie sur false, la fonction n’est pas incluse dans la charge utile de la réponse.
showHistoryOutput Chaîne de requête Paramètre facultatif. Si la valeur est définie sur true, les sorties de la fonction sont incluses dans l’historique d’exécution de l’orchestration.
createdTimeFrom Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances retournées qui ont été créées pendant ou après l’horodatage ISO8601 donné.
createdTimeTo Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances retournées qui ont été créées pendant ou avant l’horodatage ISO8601 donné.
runtimeStatus Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances retournées selon leur état d’exécution. Pour obtenir la liste des valeurs d’état d’exécution possibles, consultez l’article Interrogation des instances.
instanceIdPrefix Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, ce paramètre filtre la liste des instances retournées pour inclure uniquement les instances dont l’ID d’instance commence par la chaîne de préfixe spécifiée. Disponible à partir de la version 2.7.2 de l’extension.
top Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, limite le nombre d’instances retournées par la requête.

response

Voici un exemple de charges utiles de réponse incluant l’état de l’orchestration (mises en forme pour une meilleure lisibilité) :

[
    {
        "instanceId": "7af46ff000564c65aafbfe99d07c32a5",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:39Z",
        "lastUpdatedTime": "2018-06-04T10:46:47Z"
    },
    {
        "instanceId": "80eb7dd5c22f4eeba9f42b062794321e",
        "runtimeStatus": "Running",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:28Z",
        "lastUpdatedTime": "2018-06-04T15:18:38Z"
    },
    {
        "instanceId": "9124518926db408ab8dfe84822aba2b1",
        "runtimeStatus": "Completed",
        "input": null,
        "customStatus": null,
        "output": [
            "Hello Tokyo!",
            "Hello Seattle!",
            "Hello London!"
        ],
        "createdTime": "2018-06-04T10:46:54Z",
        "lastUpdatedTime": "2018-06-04T10:47:03Z"
    },
    {
        "instanceId": "d100b90b903c4009ba1a90868331b11b",
        "runtimeStatus": "Pending",
        "input": null,
        "customStatus": null,
        "output": null,
        "createdTime": "2018-06-04T15:18:39Z",
        "lastUpdatedTime": "2018-06-04T15:18:39Z"
    }
]

Notes

Cette opération peut être très coûteuse en termes d’E/S de stockage Azure si vous utilisez le fournisseur Stockage Azure par défaut et s’il y a beaucoup de lignes dans la table Instances. Pour plus d’informations sur la table Instance, consultez la documentation du fournisseur de stockage Azure .

Si vous obtenez plus de résultats, un jeton de continuation est retourné dans l’en-tête de réponse. Le nom de l’en-tête est x-ms-continuation-token.

Attention

Le résultat de la requête peut retourner moins d’éléments que la limite spécifiée par top. Lors de la réception des résultats, vous devez donc toujours vérifier s’il existe un jeton de continuation.

Si vous définissez la valeur du jeton de continuation dans l’en-tête de la demande suivante, vous pouvez obtenir la page de résultats suivante. Cet en-tête de demande est également nommé x-ms-continuation-token.

Vider l’historique d’une instance unique

Supprime l’historique et les artefacts associés d’une instance d’orchestration spécifiée.

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

DELETE /admin/extensions/DurableTaskExtension/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

DELETE /runtime/webhooks/durabletask/instances/{instanceId}
    ?taskHub={taskHub}
    &connection={connection}
    &code={systemKey}

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
instanceId URL L’ID de l’instance d’orchestration.

response

Les valeurs de code d’état HTTP peuvent être également être retournées.

  • HTTP 200 (OK) : L’historique d’instance a été vidé avec succès.
  • HTTP 404 (Introuvable) : L’instance spécifiée n’existe pas.

La charge utile de réponse pour le cas HTTP 200 est un objet JSON présentant le champ suivant :

Champ Type de données Description
instancesDeleted entier Nombre d’instances supprimées. Dans le cas d’une instance unique, cette valeur doit toujours être 1.

Voici un exemple de charge utile de réponse (mis en forme pour une meilleure lisibilité) :

{
    "instancesDeleted": 1
}

Vider l’historique de plusieurs instances

Vous pouvez également supprimer l’historique et les artefacts associés de plusieurs instances au sein d’un hub de tâches en supprimant {instanceId} de la demande « Vider l’historique d’une instance unique ». Pour vider l’historique de certaines instances spécifiques, utilisez les mêmes filtres que ceux décrits dans la demande « Obtenir l’état de toutes les instances ».

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

DELETE /admin/extensions/DurableTaskExtension/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

DELETE /runtime/webhooks/durabletask/instances
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &createdTimeFrom={timestamp}
    &createdTimeTo={timestamp}
    &runtimeStatus={runtimeStatus1,runtimeStatus2,...}

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
createdTimeFrom Chaîne de requête Filtre la liste des instances vidées qui ont été créées pendant ou après l’horodatage ISO8601 donné.
createdTimeTo Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances vidées qui ont été créées pendant ou avant l’horodatage ISO8601 donné.
runtimeStatus Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, filtre la liste des instances vidées selon l’état de leur runtime. Pour obtenir la liste des valeurs d’état d’exécution possibles, consultez l’article Interrogation des instances.

Notes

Cette opération peut être très coûteuse en termes d’E/S de stockage Azure si vous utilisez le fournisseur Stockage Azure par défaut et s’il y a beaucoup de lignes dans les table Instances et History. Vous trouverez plus d’informations sur ces tables dans la documentation Performances et diminution de la taille des instances dans Durable Functions (Azure Functions).

response

Les valeurs de code d’état HTTP peuvent être également être retournées.

  • HTTP 200 (OK) : L’historique d’instance a été vidé avec succès.
  • HTTP 404 (Introuvable) : Aucune instance correspondant à l’expression de filtre n’a été trouvée.

La charge utile de réponse pour le cas HTTP 200 est un objet JSON présentant le champ suivant :

Champ Type de données Description
instancesDeleted entier Nombre d’instances supprimées.

Voici un exemple de charge utile de réponse (mis en forme pour une meilleure lisibilité) :

{
    "instancesDeleted": 250
}

Raise event

Envoie un message de notification d’événement à une instance d’orchestration en cours d’exécution.

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

POST /runtime/webhooks/durabletask/instances/{instanceId}/raiseEvent/{eventName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
instanceId URL L’ID de l’instance d’orchestration.
eventName URL Le nom de l’événement que l’instance d’orchestration cible attend.
{content} Contenu de la demande La charge utile de l’événement au format JSON.

response

Plusieurs valeurs de code d’état possibles peuvent être retournées.

  • HTTP 202 (Accepted) : l’événement déclenché a été accepté pour traitement.
  • HTTP 400 (Bad request) : le contenu de la demande n’était pas de type application/json ou n’était pas un objet JSON valide.
  • HTTP 404 (Not Found) : l’instance spécifiée est introuvable.
  • HTTP 410 (Gone) : l’instance spécifiée est terminée ou a échoué et ne peut traiter aucun événement déclenché.

Voici un exemple de requête qui envoie la chaîne JSON "incr" à une instance en attente d’un événement nommé operation :

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/raiseEvent/operation?taskHub=DurableFunctionsHub&connection=Storage&code=XXX
Content-Type: application/json
Content-Length: 6

"incr"

Les réponses pour cette API sont vides.

Arrêter une instance

Arrête une instance d’orchestration en cours d’exécution.

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

POST /runtime/webhooks/durabletask/instances/{instanceId}/terminate
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Les paramètres de la demande pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que le paramètre unique suivant.

Champ Type de paramètre Description
instanceId URL L’ID de l’instance d’orchestration.
reason Chaîne de requête Optionnel. Motif d’arrêt de l’instance d’orchestration.

response

Plusieurs valeurs de code d’état possibles peuvent être retournées.

  • HTTP 202 (Accepted) : la demande d’arrêt a été acceptée pour traitement.
  • HTTP 404 (Not Found) : l’instance spécifiée est introuvable.
  • HTTP 410 (Gone) : l’instance spécifiée est terminée ou a échoué.

Voici un exemple de demande qui met fin à une instance en cours d’exécution et affiche la raison buggy (bogué) :

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/terminate?reason=buggy&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

Les réponses pour cette API sont vides.

Suspendre l’instance

Suspend une instance de l’orchestration en cours d’exécution.

Requête

Dans la version 2.x du runtime Functions, la requête est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

POST /runtime/webhooks/durabletask/instances/{instanceId}/suspend
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Champ Type de paramètre Description
instanceId URL L’ID de l’instance d’orchestration.
reason Chaîne de requête Optionnel. Motif de la suspension de l’instance de l’orchestration.

Plusieurs valeurs de code d’état possibles peuvent être retournées.

  • HTTP 202 (Accepté) : la requête de suspension a été acceptée pour traitement.
  • HTTP 404 (Not Found) : l’instance spécifiée est introuvable.
  • HTTP 410 (Supprimé) : l’instance spécifiée est terminée, a échoué ou a été arrêtée.

Les réponses pour cette API sont vides.

Reprendre l’instance

Reprend une instance de l’orchestration suspendue.

Requête

Dans la version 2.x du runtime Functions, la requête est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

POST /runtime/webhooks/durabletask/instances/{instanceId}/resume
    ?reason={text}
    &taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
Champ Type de paramètre Description
instanceId URL L’ID de l’instance d’orchestration.
reason Chaîne de requête Optionnel. Motif de reprise de l’instance de l’orchestration.

Plusieurs valeurs de code d’état possibles peuvent être retournées.

  • HTTP 202 (Accepté) : la requête de reprise a été acceptée pour traitement.
  • HTTP 404 (Not Found) : l’instance spécifiée est introuvable.
  • HTTP 410 (Supprimé) : l’instance spécifiée est terminée, a échoué ou a été arrêtée.

Les réponses pour cette API sont vides.

Instance de rembobinage (préversion)

Restaure une instance d’orchestration ayant échoué dans un état en cours d’exécution au travers de la relecture des dernières opérations ayant échoué.

Requête

Pour la version 1.x du runtime Functions, la demande est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

POST /admin/extensions/DurableTaskExtension/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

En version 2.x du runtime Functions, le format d’URL comporte les mêmes paramètres, mais présente un préfixe légèrement différent :

POST /runtime/webhooks/durabletask/instances/{instanceId}/rewind
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &reason={text}

Les paramètres de la demande pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que le paramètre unique suivant.

Champ Type de paramètre Description
instanceId URL L’ID de l’instance d’orchestration.
reason Chaîne de requête Optionnel. Motif de rembobinage de l’instance d’orchestration.

response

Plusieurs valeurs de code d’état possibles peuvent être retournées.

  • HTTP 202 (Accepté) : la requête de rembobinage a été acceptée pour traitement.
  • HTTP 404 (Not Found) : l’instance spécifiée est introuvable.
  • HTTP 410 (Supprimé) : l’instance spécifiée est terminée.

Voici un exemple de requête qui rembobine une instance ayant échoué et affiche la raison corrigé :

POST /admin/extensions/DurableTaskExtension/instances/bcf6fb5067b046fbb021b52ba7deae5a/rewind?reason=fixed&taskHub=DurableFunctionsHub&connection=Storage&code=XXX

Les réponses pour cette API sont vides.

Signaler l’entité

Envoie un message d’opération unidirectionnel à une entité durable. Si l’entité n’existe pas, elle est créée automatiquement.

Notes

Les entités durables sont disponibles à compter de Durable Functions 2.0.

Requête

La requête HTTP est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

POST /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &op={operationName}

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
entityName URL Nom (type) de l’entité.
entityKey URL Clé (ID unique) de l’entité.
op Chaîne de requête Optionnel. Nom de l’opération définie par l’utilisateur à appeler.
{content} Contenu de la demande La charge utile de l’événement au format JSON.

Voici un exemple de requête qui envoie un message « Add » défini par l’utilisateur à une entité Counter appelée steps. Le contenu du message est la valeur 5. Si l’entité n’existe pas encore, elle est créée par cette requête :

POST /runtime/webhooks/durabletask/entities/Counter/steps?op=Add
Content-Type: application/json

5

Notes

Par défaut, avec des entités basées sur une classe dans .NET, la spécification de la valeur op de delete a pour effet de supprimer l’état d’une entité. Toutefois, si l’entité définit une opération nommée delete, cette opération définie par l’utilisateur sera appelée à la place.

response

Cette opération a plusieurs réponses possibles :

  • HTTP 202 (Accepté) : L’opération de signal a été acceptée pour traitement asynchrone.
  • HTTP 400 (Requête incorrecte) : Le contenu de la requête n’était pas de type application/json ou n’était pas un objet JSON valide ou bien sa valeur entityKey n’était pas valide.
  • HTTP 404 (Introuvable) : L’entité entityName spécifiée est introuvable.

Une requête HTTP réussie ne contient pas de contenu dans la réponse. Une requête HTTP ayant échoué peut contenir des informations d’erreur au format JSON dans le contenu de la réponse.

Obtenir l’entité

Obtient l’état de l’entité spécifiée.

Requête

La requête HTTP est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

GET /runtime/webhooks/durabletask/entities/{entityName}/{entityKey}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}

response

Cette opération a deux réponses possibles :

  • HTTP 200 (OK) : L’entité spécifiée existe.
  • HTTP 404 (Introuvable) : L’entité spécifiée est introuvable.

Une réponse réussie contient l’état sérialisé JSON de l’entité en tant que contenu.

Exemple

L’exemple suivant de requête HTTP obtient l’état d’une entité Counter existante nommée steps :

GET /runtime/webhooks/durabletask/entities/Counter/steps

Si l’entité Counter contenait simplement un nombre d’étapes enregistrées dans un champ currentValue, le contenu de la réponse pourrait ressembler à ce qui suit (mise en forme pour plus de lisibilité) :

{
    "currentValue": 5
}

Lister les entités

Vous pouvez interroger plusieurs entités à l’aide de leur nom ou de la date de la dernière opération.

Requête

La requête HTTP est mise en forme comme suit (plusieurs lignes sont affichées par souci de clarté) :

GET /runtime/webhooks/durabletask/entities/{entityName}
    ?taskHub={taskHub}
    &connection={connectionName}
    &code={systemKey}
    &lastOperationTimeFrom={timestamp}
    &lastOperationTimeTo={timestamp}
    &fetchState=[true|false]
    &top={integer}

Les paramètres de requête pour cette API incluent l’ensemble par défaut mentionné précédemment, ainsi que les paramètres uniques suivants :

Champ Type de paramètre Description
entityName URL Optionnel. Lorsqu’elle est spécifiée, filtre la liste des entités retournées par nom (sans respect de la casse).
fetchState Chaîne de requête Paramètre facultatif. Si la valeur est définie sur true, l’état de l’entité sera inclus dans la charge utile de réponse.
lastOperationTimeFrom Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, il filtre la liste des entités retournées qui ont traité des opérations après l’horodatage ISO8601 donné.
lastOperationTimeTo Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, il filtre la liste des entités retournées qui ont traité des opérations avant l’horodatage ISO8601 donné.
top Chaîne de requête Paramètre facultatif. Lorsqu’il est spécifié, il limite le nombre d’entités retournées par la requête.

response

Une réponse HTTP 200 réussie contient un tableau d’entités sérialisé par du code JSON et, éventuellement, l’état de chaque entité.

Par défaut, l’opération retourne les 100 premières entités qui correspondent aux critères de la requête. L’appelant peut spécifier une valeur de paramètre de chaîne de requête pour que top retourne un autre nombre maximal de résultats. Si tous les résultats ne sont pas retournés, un jeton de continuation est également retourné dans l’en-tête de réponse. Le nom de l’en-tête est x-ms-continuation-token.

Si vous définissez la valeur du jeton de continuation dans l’en-tête de la demande suivante, vous pouvez obtenir la page de résultats suivante. Cet en-tête de demande est également nommé x-ms-continuation-token.

Exemple - Liste de toutes les entités

L’exemple de requête HTTP suivant liste toutes les entités dans le hub de tâches :

GET /runtime/webhooks/durabletask/entities

La réponse JSON peut se présenter de la façon suivante (elle a été mise en forme pour une meilleure lisibilité) :

[
    {
        "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"
    },
]

Exemple - Filtrage de la liste des entités

L’exemple de requête HTTP suivant liste uniquement les deux premières entités de type counter et récupère également leur état :

GET /runtime/webhooks/durabletask/entities/counter?top=2&fetchState=true

La réponse JSON peut se présenter de la façon suivante (elle a été mise en forme pour une meilleure lisibilité) :

[
    {
        "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 }
    }
]

Étapes suivantes

Découvrez comment utiliser Application Insights pour surveiller vos fonctions durables