Integrating visual intelligence service

Prerequisites

• Obtain the API semantics and required parameters for the service that you want to call. For more information, see the visual intelligence official website or the List of supported visual intelligence services and API operations section in this topic.
• Ensure that the execution role for the flow has the required permissions to call the API operation, such as AliyunVIAPIFullAccess. For more information, see Execution roles.

Procedure

1. Define the API operation to call in the flow.
   You can call the API operations of visual intelligence services in a task step. In the task step, specify the Action parameter instead of the resourceArn parameter in the following format.

   action: {serviceName}:{apiName}

   • {serviceName}: The service name. For more information, see the List of supported visual intelligence services and API operations.
   • {apiName}: The name of the API operation to call. For more information, see the List of supported visual intelligence services and API operations.
2. Specify API parameters.

   Specify the API call parameters in the ServiceParams section. Serverless Workflow validates the parameters against the API definition for the service.

   For example, consider the ClassifyCommodity API of the visual intelligence service. The following code shows the corresponding task in Flow Definition Language (FDL). For more information about the API, see Product categorization.

   ...
     - type: task
       name: APIClassifyCommodity
       action: goodstech:ClassifyCommodity
       inputMappings:
         - target: image
           source: $input.imageURL
       serviceParams: # Describes the parameters required for ClassifyCommodity. For the parameter list, see the API description.
         ImageURL: $.image

   In this example, action specifies the service name and API name for the call. The ServiceParams section contains the parameters for the corresponding API.

3. Handle errors.
   If an API call fails, Serverless Workflow returns the error and cause keys in the output of the step. You can use the error key to catch the error type and implement corresponding logic, such as a redirect. Serverless Workflow adds the {serviceName}. prefix to the original error code that is returned by the service to be used as a catch identifier. For example, consider the error codes of goodstech:ClassifyCommodity. For more information, see Error codes.

   ...
   steps:
     - type: task
       name: APIClassifyCommodity
       action: goodstech:ClassifyCommodity # Format: {serviceName}:{apiName}. See the API list at the end of this topic.
       ...
       retry: # Retry after catching an error.
         - errors:
           - goodstech.InternalError.Busy
           intervalSeconds: 10
           maxAttempts: 2
           multiplier: 2
       catch: # Redirect after catching an error.
         - errors:
           - goodstech.CommonError
           - goodstech.IllegalUrlParameter
           - goodstech.InvalidParameter
           goto: xxxxx

   In this case, InternalError.Busy is the original service error code. To catch this error code in the flow, you must add the service prefix goodstech..

Example: Orchestrate a visual intelligence image recognition API

This example uses a visual intelligence API for image recognition to categorize products in an image. For more information, see Product categorization.

version: v1 
type: flow
steps:
  - type: task
    name: APIClassifyCommodity
    action: goodstech:ClassifyCommodity # Format: {serviceName}:{apiName}. See the API list at the end of this topic.
    inputMappings: # Map the input variable for the ClassifyCommodity parameters.
      - target: image
        source: $input.imageURL
    outputMappings: # Map the output to a local variable.
      - target: classifyCommodity_Categories
        source: $local.Data.Categories
    serviceParams: # Describes the parameters required for ClassifyCommodity. For the parameter list, see the API description.
      ImageURL: $.image
    retry: # Retry after catching an error.
      - errors:
        - goodstech.InternalError.Busy
        intervalSeconds: 10
        maxAttempts: 2
        multiplier: 2
    catch: # Redirect after catching an error.
      - errors:
        - goodstech.CommonError
        - goodstech.IllegalUrlParameter
        - goodstech.InvalidParameter
        goto: ExecFailed
  - type: foreach # According to the ClassifyCommodity response parameters, the API returns an array. Process this type of data in a foreach step in the subsequent flow.
    name: ElemDealt
    iterationMapping:
      collection: $.classifyCommodity_Categories
      item: catagory
    steps:
      - type: pass
        name: pass1
        inputMappings:
          # the index can be from context
          - target: index
            source: $context.step.iterationIndex
          - target: catagory
            source: $input.catagory
    end: true
  - type: fail
    name: ExecFailed

{
    # The URL of the image to process.
    "imageURL": "https://viapi-demo.oss-cn-shanghai.aliyuncs.com/viapi-demo/images/DetectImageElements/detect-elements-src.png"
}

List of supported visual intelligence services and API operations