Obsługa błędów

Z tego przewodnika dowiesz się, jak zarządzać błędami, które występują podczas wykonywania kroku przepływu. Możesz określić, czy nieudany krok wymaga działania użytkownika, czy można go ponowić.

  • Zwróć błąd, który można naprawić: dodaj do dziennika błędów przycisk, który przekieruje użytkownika do karty konfiguracji kroku, umożliwiając mu zmodyfikowanie danych wejściowych w celu rozwiązania problemu. Aby oznaczyć błąd jako wymagający podjęcia działania, zwróć wartość AddOnsResponseService.ErrorActionability.ACTIONABLE. Aby oznaczyć błąd jako nie wymagający działania, zwróć wartość AddOnsResponseService.ErrorActionability.NOT_ACTIONABLE.
  • Ponawianie kroku po wystąpieniu błędu: przepływ próbuje ponownie wykonać krok maksymalnie 5 razy, zanim się zatrzyma. Aby oznaczyć błąd jako taki, który można ponowić, zwróć wartość AddOnsResponseService.ErrorRetryability.RETRYABLE. Aby oznaczyć błąd, którego nie można ponowić, zwróć wartość AddOnsResponseService.ErrorRetryability.NOT_RETRYABLE.

Możesz też tworzyć niestandardowe logi błędów z elementami, hiperlinkami i sformatowanym tekstem, aby przekazywać użytkownikom bardziej szczegółowe informacje o błędzie.

Zwracanie błędu, który można naprawić

W tym przykładzie tworzymy krok, w którym użytkownik jest proszony o podanie liczby ujemnej. Jeśli użytkownik wpisze liczbę dodatnią, krok zwróci błąd, który można naprawić, i poprosi użytkownika o poprawienie danych wejściowych.

Poniższy plik manifestu określa dane wejściowe i wyjściowe kroku oraz funkcje, które należy wywołać w celu konfiguracji i wykonania.

JSON

{
  "timeZone": "America/Toronto",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Retry Errors Example",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "returnElementError",
          "state": "ACTIVE",
          "name": "Return Element Error Action",
          "description": "To notify the user that some error has occurred",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "The input from the user",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "output_1",
                "description": "The output",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onConfiguration",
            "onExecuteFunction": "onExecution"
          }
        }
      ]
    }
  }
}

Poniższy kod tworzy kartę konfiguracji i obsługuje logikę wykonania, w tym obsługę błędów.

Google Apps Script

/**
 * Returns a configuration card for the step.
 * This card contains a text input field for the user.
 */
function onConfiguration() {
  let section = CardService.newCardSection()
    .addWidget(CardService.newTextInput()
      .setFieldName("value1")
      .setId("value1")
      .setTitle("Please input negative numbers!"));
  const card = CardService.newCardBuilder().addSection(section).build();
  return card;
}

/**
 * Gets an integer value from variable data, handling both string and integer formats.
 * @param {Object} variableData The variable data object from the event.
 * @return {number} The extracted integer value.
 */
function getIntValue(variableData) {
  if (variableData.stringValues) {
    return parseInt(variableData.stringValues[0]);
  }
  return variableData.integerValues[0];
}

/**
 * Executes the step.
 * If the user input is a positive number, it throws an error and returns an
 * actionable error message. Otherwise, it returns the input as an output variable.
 * @param {Object} e The event object from the workflow.
 */
function onExecution(e) {
  try {
    var input_value = getIntValue(e.workflow.actionInvocation.inputs["value1"]);
    if (input_value > 0) {
      throw new Error('Found invalid positive input value!');
    }

    // If execution is successful, return the output variable and a log.
    const styledText_1 = AddOnsResponseService.newStyledText()
      .setText("Execution completed, the number you entered was: ")
      .addStyle(AddOnsResponseService.TextStyle.ITALIC)
      .addStyle(AddOnsResponseService.TextStyle.UNDERLINE);
    const styledText_2 = AddOnsResponseService.newStyledText().setText(input_value)
      .setFontWeight(AddOnsResponseService.FontWeight.BOLD);

    const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
      .setVariables({
        "output_1": AddOnsResponseService.newVariableData().addStringValue(input_value)
      })
      .setLog(AddOnsResponseService.newWorkflowTextFormat()
        .addTextFormatElement(
          AddOnsResponseService.newTextFormatElement().setStyledText(styledText_1)
        ).addTextFormatElement(
          AddOnsResponseService.newTextFormatElement().setStyledText(styledText_2)
        ));

    let hostAppAction = AddOnsResponseService.newHostAppAction().setWorkflowAction(workflowAction);
    return AddOnsResponseService.newRenderActionBuilder().setHostAppAction(hostAppAction).build();

  } catch (err) {
    // If an error occurs, return an actionable error action.
    Logger.log('An error occurred: ' + err.message);

    const workflowAction = AddOnsResponseService.newReturnElementErrorAction()
      // Sets the user-facing error message.
      .setErrorLog(
        AddOnsResponseService.newWorkflowTextFormat()
        .addTextFormatElement(
          AddOnsResponseService.newTextFormatElement().setText("Failed because of invalid input values!"))
      )
      // Makes the error actionable, allowing the user to correct the input.
      .setErrorActionability(AddOnsResponseService.ErrorActionability.ACTIONABLE)
      // Specifies that the error is not automatically retried.
      .setErrorRetryability(AddOnsResponseService.ErrorRetryability.NOT_RETRYABLE);

    let hostAppAction = AddOnsResponseService.newHostAppAction().setWorkflowAction(workflowAction);
    return AddOnsResponseService.newRenderActionBuilder().setHostAppAction(hostAppAction).build();
  }
}

Ponawianie kroku po wystąpieniu błędu

W tym przykładzie tworzymy krok, który symuluje tymczasową awarię. Jeśli wystąpi błąd, krok zwróci błąd, który można ponowić, co spowoduje ponowne uruchomienie kroku w przepływie.

Plik manifestu określa krok.

JSON

{
  "timeZone": "America/Toronto",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Retry Errors Example",
      "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/pets_black_48dp.png",
      "useLocaleFromApp": true
    },
    "flows": {
      "workflowElements": [
        {
          "id": "retryError",
          "state": "ACTIVE",
          "name": "Retry an error",
          "description": "Simulates a temporary failure and retries the step.",
          "workflowAction": {
            "inputs": [
              {
                "id": "value1",
                "description": "Any input value",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "outputs": [
              {
                "id": "output_1",
                "description": "The output",
                "cardinality": "SINGLE",
                "dataType": {
                  "basicType": "STRING"
                }
              }
            ],
            "onConfigFunction": "onRetryConfiguration",
            "onExecuteFunction": "onRetryExecution"
          }
        }
      ]
    }
  }
}

Poniższy kod tworzy kartę konfiguracji i obsługuje logikę ponawiania.

Google Apps Script

/**
 * Returns a configuration card for the step.
 * This card contains a text input field for the user.
 */
function onRetryConfiguration() {
  let section = CardService.newCardSection()
    .addWidget(CardService.newTextInput()
      .setFieldName("value1")
      .setId("value1")
      .setTitle("Enter any value"));
  const card = CardService.newCardBuilder().addSection(section).build();
  return card;
}

/**
 * Executes the step and simulates a transient error.
 * This function fails 80% of the time. When it fails, it returns an
 * error that can be retried.
 * @param {Object} e The event object from the workflow.
 */
function onRetryExecution(e) {
  try {
    // Simulate a transient error that fails 80% of the time.
    if (Math.random() < 0.8) {
      throw new Error('Simulated transient failure!');
    }

    // If execution is successful, return the output variable and a log.
    var input_value = e.workflow.actionInvocation.inputs["value1"].stringValues[0];
    const styledText = AddOnsResponseService.newStyledText()
      .setText(`Execution succeeded for input: ${input_value}`);

    const workflowAction = AddOnsResponseService.newReturnOutputVariablesAction()
      .setVariables({
        "output_1": AddOnsResponseService.newVariableData().addStringValue(input_value)
      })
      .setLog(AddOnsResponseService.newWorkflowTextFormat()
        .addTextFormatElement(
          AddOnsResponseService.newTextFormatElement().setStyledText(styledText)
        ));

    let hostAppAction = AddOnsResponseService.newHostAppAction().setWorkflowAction(workflowAction);
    return AddOnsResponseService.newRenderActionBuilder().setHostAppAction(hostAppAction).build();

  } catch (err) {
    // If a transient error occurs, return an error message saying the step tries to run again.
    Logger.log('A error occurred, trying to run the step again: ' + err.message);

    const workflowAction = AddOnsResponseService.newReturnElementErrorAction()
      // Sets the user-facing error message.
      .setErrorLog(
        AddOnsResponseService.newWorkflowTextFormat()
        .addTextFormatElement(
          AddOnsResponseService.newTextFormatElement().setText("A temporary error occurred. The step will be retried."))
      )
      // Makes the error not actionable by the user.
      .setErrorActionability(AddOnsResponseService.ErrorActionability.NOT_ACTIONABLE)
      // Specifies that the error is automatically retried.
      .setErrorRetryability(AddOnsResponseService.ErrorRetryability.RETRYABLE);

    let hostAppAction = AddOnsResponseService.newHostAppAction().setWorkflowAction(workflowAction);
    return AddOnsResponseService.newRenderActionBuilder().setHostAppAction(hostAppAction).build();
  }
}