Directly call from an Android client

Background information

Before you call from a miniapp, you must obtain a temporary access credential from the Security Token Service (STS). Alibaba Cloud STS is a service for managing temporary access permissions. You can use STS to issue temporary access credentials to users. These users can then use the credentials to call Visual Intelligence API services for a limited time. Temporary credentials protect your long-term keys and improve your account security. For more information about how to obtain a temporary access credential, see Get a temporary identity credential for a role.

Prerequisites

Obtain an STS temporary credential:

1. Grant permissions

   Before you obtain an STS temporary credential, the caller, which can be a Resource Access Management (RAM) user or a RAM role, must have permission to call STS API operations. You can grant this permission by creating a RAM access policy. For information about the setup steps and policy examples, see Use an STS temporary access credential to access OSS. Configure fine-grained access policies as needed to avoid granting excessive permissions. For more information about how to configure fine-grained custom policies, see Visual Intelligence API custom policy reference.

   Important

   To proceed, the caller (RAM user or RAM role) must be granted the following permissions:

   • AliyunSTSAssumeRoleAccess (Permission to call the STS AssumeRole API operation).

   • AliyunVIAPIFullAccess (This example grants full management permissions for the Visual Intelligence API. In a production environment, create fine-grained access policies as needed to avoid the risks of excessive permissions. For more information about how to configure custom policies, see Visual Intelligence API custom policy reference).

2. Call the AssumeRole API operation

   Use the authorized RAM user or RAM role to call the AssumeRole API operation. Specify the required parameters as described in the API documentation. For more information, see AssumeRole.

3. Use the STS token

   After you successfully call the AssumeRole API operation, you receive an STS token that contains an AccessKeyId, AccessKeySecret, and SecurityToken, as shown in the following code.

   When you call other Alibaba Cloud service API operations, replace <ALIBABA_CLOUD_ACCESS_KEY_ID>, <ALIBABA_CLOUD_ACCESS_KEY_SECRET>, and <ALIBABA_CLOUD_SECURITY_TOKEN> in your code with the temporary AccessKeyId, AccessKeySecret, and SecurityToken from the STS token.

   {
     "RequestId": "429D9967-C809-5A30-B65E-9B742CF*****",
     "AssumedRoleUser": {
       "Arn": "acs:ram::175805416243****:role/STStokenTestRole/STSsessionName",
       "AssumedRoleId": "39779315882322****:STSsessionName"
     },
     "Credentials": {
       "SecurityToken": "exampleToken",
       "AccessKeyId": "STS.exampleAccessKeyID",
       "AccessKeySecret": "exampleAccessKeySecret",
       "Expiration": "2024-06-12T03:21:29Z"
     }
   }

SDK example

To call the API directly from an Android client, see the Java SDK example. The SDK supports calls that use local files or any URL.

This topic uses bank card recognition (RecognizeBankCard) as an example. It shows only the key steps and code. For a complete example, download the AndroidDemo. If you call other algorithms, you must modify the code according to the comments and your business needs.

Add dependencies to the application's build.gradle file

// 1. For more information about the SDK, see https://help.aliyun.com/document_detail/153132.html
implementation("com.aliyun:ocr20191230:1.0.23") {
    exclude group: 'xml-apis', module: 'xml-apis'
    exclude group: 'dom4j', module: 'dom4j'
}

Initialize the client

// Replace <ALIBABA_CLOUD_ACCESS_KEY_ID>, <ALIBABA_CLOUD_ACCESS_KEY_SECRET>, and <ALIBABA_CLOUD_SECURITY_TOKEN>
// with the temporary AccessKeyId, AccessKeySecret, and SecurityToken from the STS token data.
String accessKeyId = "<ALIBABA_CLOUD_ACCESS_KEY_ID>";
String accessKeySecret = "<ALIBABA_CLOUD_ACCESS_KEY_SECRET>";
String securityToken = "<ALIBABA_CLOUD_SECURITY_TOKEN>";

Config config = new Config()
        // AccessKey ID
        .setAccessKeyId(accessKeyId)
        // AccessKey secret
        .setAccessKeySecret(accessKeySecret)
        // Security Token Service token
        .setSecurityToken(securityToken); 

// 3. The endpoint. Note: Change this to the endpoint of the corresponding category. For more information, see https://help.aliyun.com/document_detail/143103.html
config.endpoint = "ocr.cn-shanghai.aliyuncs.com";
client = new Client(config);

Call the API

/**
 * Call the API for a file in an OSS bucket in the China (Shanghai) region. This example uses RecognizeBankCard.
 * @param view
 */
public void callApiShanghaiOss(View view) {

    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                Log.d(TAG, String.format("Start calling the API: %s %s", "RecognizeBankCard", "http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg"));
                // 4. This example uses RecognizeBankCard from the OCR category. For other capabilities, use the packages and classes of the corresponding categories. For information about how to set request parameters, see the documentation for the specific capability.
                com.aliyun.ocr20191230.models.RecognizeBankCardRequest recognizeBankCardRequest = new com.aliyun.ocr20191230.models.RecognizeBankCardRequest()
                        .setImageURL("http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg");
                com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
                // 5. This example uses RecognizeBankCard from the OCR category. For other capabilities, use the packages and classes of the corresponding categories. Note that you must also change the method name recognizeBankCardWithOptions to the method name of the corresponding capability.
                RecognizeBankCardResponse resp = client.recognizeBankCardWithOptions(recognizeBankCardRequest, runtime);
                // Get the complete result. Some capabilities output a URL. The URL may have encoding issues after being converted using toJSONString. However, you can retrieve individual fields without any issues.
                Log.d(TAG, String.format("%s", com.aliyun.teautil.Common.toJSONString(TeaModel.buildMap(resp))));
                // Get a single field. This is just an example. For the fields of a specific capability, see the documentation for that capability.
                Log.d(TAG, String.format("%s", resp.getBody().getData().getCardNumber()));
                showToastMsg("Call successful. Bank card number: " + resp.getBody().getData().getCardNumber());
            } catch (com.aliyun.tea.TeaException teaException) {
                Log.d(TAG, "teaException.getCode(): " + teaException.getCode());
                // Handle the exception.
            } catch (Exception e) {
                e.printStackTrace();
                Log.e(TAG, e.getMessage());
            }
        }
    }).start();

/**
 * Call the API for a local file. This example uses RecognizeBankCard.
 * @param view
 */
public void callApiLocal(View view) {

    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                // Change filePath to the actual path of your file.
                String filePath = "resource/test_images/yhk1.jpg";
                Log.d(TAG, String.format("Start calling the API: %s %s", "RecognizeBankCard", filePath));
                // Use a file. The file is passed to the API operation as an inputStream. This example shows how to convert a file in the assets directory to a stream. If the file is from another source, such as an SD card or a camera, see the Android developer documentation or tutorials to learn how to convert the file to a stream before passing it.
                InputStream inputStream = MainActivity.this.getAssets().open(filePath);
                // 4. This example uses RecognizeBankCard from the OCR category. For other capabilities, use the packages and classes of the corresponding categories. For information about how to set request parameters, see the documentation for the specific capability.
                com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest recognizeBankCardAdvanceRequest = new com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest()
                        .setImageURLObject(inputStream);
                com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
                // 5. This example uses RecognizeBankCard from the OCR category. For other capabilities, use the packages and classes of the corresponding categories. Note that you must also change the method name recognizeBankCardAdvance to the method name of the corresponding capability.
                RecognizeBankCardResponse resp = client.recognizeBankCardAdvance(recognizeBankCardAdvanceRequest, runtime);
                // Get the complete result. Some capabilities output a URL. The URL may have encoding issues after being converted using toJSONString. However, you can retrieve individual fields without any issues.
                Log.d(TAG, String.format("%s", com.aliyun.teautil.Common.toJSONString(TeaModel.buildMap(resp))));
                // Get a single field. This is just an example. For the fields of a specific capability, see the documentation for that capability.
                Log.d(TAG, String.format("%s", resp.getBody().getData().getCardNumber()));
                showToastMsg("Call successful. Bank card number: " + resp.getBody().getData().getCardNumber());
            } catch (com.aliyun.tea.TeaException teaException) {
                Log.d(TAG, "teaException.getCode(): " + teaException.getCode());
                // Handle the exception.
            } catch (java.io.FileNotFoundException e) {
                showToastMsg("File not found. Check if the filePath in the code is correct.");
                Log.e(TAG, e.getMessage());
            } catch (Exception e) {
                e.printStackTrace();
                Log.e(TAG, e.getMessage());
            }
        }
    }).start();

}

/**
 * Call the API for a file at any URL. This example uses RecognizeBankCard.
 * @param view
 */
public void callApiAnyUrl(View view) {

    new Thread(new Runnable() {
        @Override
        public void run() {
            try {
                Log.d(TAG, String.format("Start calling the API: %s %s", "RecognizeBankCard", "http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg"));
                // Use any URL
                URL url = new URL("http://viapi-test.oss-cn-shanghai.aliyuncs.com/viapi-3.0domepic/ocr/RecognizeBankCard/yhk1.jpg");
                InputStream inputStream = url.openConnection().getInputStream();
                // 4. This example uses RecognizeBankCard from the OCR category. For other capabilities, use the packages and classes of the corresponding categories. For information about how to set request parameters, see the documentation for the specific capability.
                com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest recognizeBankCardAdvanceRequest = new com.aliyun.ocr20191230.models.RecognizeBankCardAdvanceRequest()
                        .setImageURLObject(inputStream);
                com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
                // 5. This example uses RecognizeBankCard from the OCR category. For other capabilities, use the packages and classes of the corresponding categories. Note that you must also change the method name recognizeBankCardAdvance to the method name of the corresponding capability.
                RecognizeBankCardResponse resp = client.recognizeBankCardAdvance(recognizeBankCardAdvanceRequest, runtime);
                // Get the complete result. Some capabilities output a URL. The URL may have encoding issues after being converted using toJSONString. However, you can retrieve individual fields without any issues.
                Log.d(TAG, String.format("%s", com.aliyun.teautil.Common.toJSONString(TeaModel.buildMap(resp))));
                // Get a single field. This is just an example. For the fields of a specific capability, see the documentation for that capability.
                Log.d(TAG, String.format("%s", resp.getBody().getData().getCardNumber()));
                showToastMsg("Call successful. Bank card number: " + resp.getBody().getData().getCardNumber());
            } catch (com.aliyun.tea.TeaException teaException) {
                Log.d(TAG, "teaException.getCode(): " + teaException.getCode());
                // Handle the exception.
            } catch (Exception e) {
                e.printStackTrace();
                Log.e(TAG, e.getMessage());
            }
        }
    }).start();

}