Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Modelli di integrazione dei servizi

AWS Step Functions si integra con i servizi direttamente in Amazon States Language. È possibile controllare questi servizi AWS utilizzando tre modelli di integrazione del servizio.

Ognuno di questi modelli di integrazione del servizio è controllato dal modo in cui si crea una URI nel campo "Resource" della definizione dell'attività.

Per informazioni sulla configurazione AWS Identity and Access Management (IAM) per i servizi integrati, consulta. Politiche IAM per servizi integrati

Richiesta e risposta

Quando si specifica un servizio nella "Resource" stringa dello stato dell'attività e si fornisce solo la risorsa, Step Functions attenderà una risposta HTTP e quindi passerà allo stato successivo. Step Functions non aspetterà il completamento di un lavoro.

L'esempio seguente mostra come pubblicare un argomento di Amazon SNS.

"Send message to SNS":{  
   "Type":"Task",
   "Resource":"arn:aws:states:::sns:publish",
   "Parameters":{  
      "TopicArn":"arn:aws:sns:us-east-1:123456789012:myTopic",
      "Message":"Hello from Step Functions!"
   },
   "Next":"NEXT_STATE"
}

Questo esempio fa riferimento all'API Publish di Amazon SNS. Il flusso di lavoro avanza allo stato successivo dopo aver richiamato l'API Publish.

Esegui un processo (.sync)

Per i servizi integrati come AWS Batch Amazon ECS, Step Functions può attendere il completamento di una richiesta prima di passare allo stato successivo. Per far attendere Step Functions, specifica il "Resource" campo nella definizione dello stato dell'attività con il .sync suffisso aggiunto dopo l'URI della risorsa.

Ad esempio, quando inviate un AWS Batch lavoro, utilizzate il "Resource" campo nella definizione della macchina a stati, come illustrato in questo esempio.

"Manage Batch task": {
  "Type": "Task",
  "Resource": "arn:aws:states:::batch:submitJob.sync",
  "Parameters": {
    "JobDefinition": "arn:aws:batch:us-east-2:123456789012:job-definition/testJobDefinition",
    "JobName": "testJob",
    "JobQueue": "arn:aws:batch:us-east-2:123456789012:job-queue/testQueue"
  },
  "Next": "NEXT_STATE"
}

Se la .sync parte viene aggiunta alla risorsa Amazon Resource Name (ARN), Step Functions attende il completamento del lavoro. Dopo la chiamata AWS Batch submitJob, il flusso di lavoro si mette in pausa. Una volta completato il lavoro, Step Functions passa allo stato successivo. Per ulteriori informazioni, vedere il progetto AWS Batch di esempio:Gestire un processo batch (AWS Batch,Amazon SNS).

Se un'attività che utilizza questo modello di integrazione del servizio (.sync) viene interrotta e Step Functions non è in grado di annullarla, potrebbero essere addebitati costi aggiuntivi dal servizio integrato. Un'attività può essere interrotta se:

Step Functions farà del suo meglio per annullare l'operazione. Ad esempio, se un'states:startExecution.syncattività Step Functions viene interrotta, chiamerà l'azione StopExecution API Step Functions. Tuttavia, è possibile che Step Functions non sia in grado di annullare l'operazione. I motivi di ciò includono, a titolo esemplificativo ma non esaustivo:

Quando si utilizza il modello di integrazione dei .sync servizi, Step Functions utilizza il polling che utilizza la quota e gli eventi assegnati per monitorare lo stato di un lavoro. Per .sync le chiamate all'interno dello stesso account, Step Functions utilizza EventBridge eventi ed esegue il polling delle API specificate nello stato. Task Per le chiamate tra più account.sync, Step Functions utilizza solo il polling. Ad esempio, forstates:StartExecution.sync, Step Functions esegue il polling sull'DescribeExecutionAPI e utilizza la quota assegnata.

Per consultare un elenco di ciò che supportano i servizi integrati in attesa del completamento di un processo (.sync), vedi Integrazioni ottimizzate per Step Functions.

In alcuni casi, potresti volere che Step Functions continui il flusso di lavoro prima che il lavoro sia completamente completato. È possibile ottenere ciò nello stesso modo in cui si utilizza il modello Attendere un callback con il token dell’attività di integrazione dei servizi. Per fare ciò, passa un token di attività al tuo job, quindi restituiscilo utilizzando una chiamata SendTaskSuccesso SendTaskFailureAPI. Step Functions utilizzerà i dati forniti in quella chiamata per completare l'attività, interrompere il monitoraggio del lavoro e continuare il flusso di lavoro.

Attendere un callback con il token dell’attività

Le attività di callback forniscono un modo per mettere in pausa un flusso di lavoro finché non viene restituito il token dell’attività. Per un'operazione potrebbe essere necessario attendere un’approvazione umana, integrarsi con una terza parte oppure chiamare i sistemi legacy. Per attività come queste, puoi mettere in pausa Step Functions finché l'esecuzione del flusso di lavoro non raggiunge la quota di servizio di un anno (vedi,Quote relative alla limitazione statale) e attendere il completamento di un processo o flusso di lavoro esterno. In queste situazioni Step Functions consente di passare un token di attività alle integrazioni del servizio AWS SDK e anche ad alcune integrazioni di servizi ottimizzati. L'attività verrà messa in pausa finché non riceverà la restituzione del token con una chiamata SendTaskSuccess o SendTaskFailure.

Se uno Task stato che utilizza il token di attività di callback scade, viene generato un nuovo token casuale. È possibile accedere ai token delle attività dall'oggetto context.

Per essere utilizzata .waitForTaskToken con un'integrazione AWS SDK, l'API utilizzata deve disporre di un campo di parametri in cui inserire il token dell'attività.

Per consultare un elenco di ciò che supportano i servizi integrati in attesa del token di un'attività (.waitForTaskToken), vedi Integrazioni ottimizzate per Step Functions.

Esempio di token di un’attività

In questo esempio, un flusso di lavoro Step Functions deve integrarsi con un microservizio esterno per eseguire una verifica del credito come parte di un flusso di lavoro di approvazione. Step Functions pubblica un messaggio Amazon SQS che include un task token come parte del messaggio. Un sistema esterno si integra con Amazon SQS e rimuove il messaggio dalla coda. Al termine, restituisce il risultato e il task token originale. Step Functions continua quindi con il suo flusso di lavoro.

Il "Resource" campo della definizione dell'attività che fa riferimento ad Amazon SQS include .waitForTaskToken aggiunto alla fine.

"Send message to SQS": {
  "Type": "Task",
  "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
  "Parameters": {
    "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
    "MessageBody": {
        "Message": "Hello from Step Functions!",
        "TaskToken.$": "$$.Task.Token"
     }
  },
  "Next": "NEXT_STATE"
}

Questo dice a Step Functions di mettere in pausa e attendere il task token. Quando si specifica una risorsa utilizzando .waitForTaskToken, il token di attività è accessibile nel campo "Parameters" della definizione dello stato con una designazione speciale di percorso ($$.Task.Token). Il $$. iniziale indica che il percorso accede all’oggetto contestuale e ottiene il token di attività per l'attività corrente in un’esecuzione in corso.

Quando viene completato, il servizio esterno chiama SendTaskSuccess o SendTaskFailure con taskToken incluso. Solo allora il flusso di lavoro procede allo stato successivo.

Ottieni un Token dall’oggetto contestuale

L'oggetto contestuale è un oggetto JSON interno che contiene informazioni sull'esecuzione. Come input di stato, è possibile accedervi con un percorso dal campo "Parameters" durante un'esecuzione. Quando l’accesso viene eseguito dall'interno di una definizione di attività, include informazioni sull'esecuzione specifica, tra cui il token dell’attività.

{
    "Execution": {
        "Id": "arn:aws:states:us-east-1:123456789012:execution:stateMachineName:executionName",
        "Input": {
           "key": "value"
        },
        "Name": "executionName",
        "RoleArn": "arn:aws:iam::123456789012:role...",
        "StartTime": "2019-03-26T20:14:13.192Z"
    },
    "State": {
        "EnteredTime": "2019-03-26T20:14:13.192Z",
        "Name": "Test",
        "RetryCount": 3
    },
    "StateMachine": {
        "Id": "arn:aws:states:us-east-1:123456789012:stateMachine:stateMachineName",
        "Name": "name"
    },
    "Task": {
        "Token": "h7XRiCdLtd/83p1E0dMccoxlzFhglsdkzpK9mBVKZsp7d9yrT1W"
    }
}

È possibile accedere al token dell’attività utilizzando un percorso speciale dall'interno del campo "Parameters" della definizione dell'attività. Per accedere all’input o all’oggetto contestuale, specificare per prima cosa che il parametro sarà un percorso aggiungendo .$ al nome del parametro. Quanto segue specifica i nodi sia dall'input sia dall’oggetto contestuale in una specifica "Parameters".

"Parameters": {
   "Input.$": "$",
   "TaskToken.$": "$$.Task.Token"
 },

In entrambi i casi, l'aggiunta .$ al nome del parametro indica a Step Functions di aspettarsi un percorso. Nel primo caso, "$" è un percorso che include l'intero input. Nel secondo caso, $$. specifica che il percorso potrà accedere all'oggetto contestuale e $$.Task.Token imposta il parametro al valore del token di attività nell’oggetto contestuale di un’esecuzione.

Nell'esempio di Amazon SQS, .waitForTaskToken nel "Resource" campo indica a Step Functions di attendere la restituzione del token dell'attività. Il "TaskToken.$": "$$.Task.Token" parametro passa quel token come parte del messaggio Amazon SQS.

"Send message to SQS": {
  "Type": "Task",
  "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
  "Parameters": {
    "QueueUrl": "https://sqs.us-east-2.amazonaws.com/123456789012/myQueue",
    "MessageBody": {
        "Message": "Hello from Step Functions!",
        "TaskToken.$": "$$.Task.Token"
     }
  },
  "Next": "NEXT_STATE"
}

Per ulteriori informazioni sugli oggetti contesto, vedi Oggetto Context nella sezione Elaborazione di input e output di questa guida.

Configurazione di un timeout Heartbeat per un’operazione in attesa

Un'operazione in attesa del token di attività attenderà che l'esecuzione raggiunga la quota di servizio di un anno (vedi Quote relative alla limitazione statale). Per evitare il blocco delle esecuzioni è possibile configurare un intervallo di timeout heartbeat nella definizione della macchina a stati. Utilizzare il campo HeartbeatSeconds per specificare l'intervallo di timeout.

{
  "StartAt": "Push to SQS",
  "States": {
    "Push to SQS": {
      "Type": "Task",
      "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
      "HeartbeatSeconds": 600,
      "Parameters": {
        "MessageBody": { "myTaskToken.$": "$$.Task.Token" },
        "QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/push-based-queue"
      },
      "ResultPath": "$.SQS",
      "End": true
    }
  }
}

In questa definizione di macchina a stati, un'attività invia un messaggio ad Amazon SQS e attende che un processo esterno richiami il token di attività fornito. Il campo "HeartbeatSeconds": 600 imposta l'intervallo di timeout heartbeat su 10 minuti. L'operazione attenderà che il token dell’attività venga restituito con una di queste azioni API:

Se l'attività di attesa non riceve un token di attività valido in un periodo di 10 minuti, l'operazione ha esito negativo con nome di errore States.Timeout.

Per ulteriori informazioni, consulta il progetto di esempio dell'attività di callback: Esempio di pattern di callback (Amazon SQS, Amazon SNS, Lambda) .