Integrate EOS

Choose your integration path

EOS supports two SDK paths. Pick the one that matches your operation type:

Prerequisites

Before you begin, make sure you have:

• An Alibaba Cloud account with the required permissions

• One of the following system policies attached to your RAM user or RAM role:

  • AliyunEnsFullAccess — full read/write access to Edge Node Service (ENS). Use with caution.

  • AliyunEnsEOSFullAccess — full read/write access to EOS

• Java development environment (for the examples in this topic)

For identity setup, see Identity. For permission configuration, see Authorization management.

Step 1: Create a bucket

Use the ENS SDK to create a bucket. ListBuckets and PutBucket are not compatible with the OSS SDK — always use the ENS SDK for these two operations.

package com.aliyun.sample;

import com.aliyun.tea.*;

public class Sample {

    public static com.aliyun.teaopenapi.Client createClient(String accessKeyId, String accessKeySecret) throws Exception {
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
                // Required. Specify your AccessKey ID.
                .setAccessKeyId(accessKeyId)
                // Required. Specify your AccessKey secret.
                .setAccessKeySecret(accessKeySecret);
        // ENS endpoint — not the EOS endpoint
        config.endpoint = "ens.aliyuncs.com";
        return new com.aliyun.teaopenapi.Client(config);
    }

    public static com.aliyun.teaopenapi.models.Params createApiInfo() throws Exception {
        com.aliyun.teaopenapi.models.Params params = new com.aliyun.teaopenapi.models.Params()
                .setAction("PutBucket")
                .setVersion("2017-11-10")
                .setProtocol("HTTPS")
                .setMethod("POST")
                .setAuthType("AK")
                .setStyle("RPC")
                .setPathname("/")
                .setReqBodyType("json")
                .setBodyType("json");
        return params;
    }

    public static void main(String[] args_) throws Exception {
        // Read credentials from environment variables.
        // Make sure ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET are set.
        com.aliyun.teaopenapi.Client client = Sample.createClient(
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        com.aliyun.teaopenapi.models.Params params = Sample.createApiInfo();

        java.util.Map<String, Object> body = new java.util.HashMap<>();
        body.put("BucketName", "global-eos-test1");  // Replace with your bucket name
        body.put("BucketAcl", "private");             // ACL: private, public-read, or public-read-write

        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        com.aliyun.teaopenapi.models.OpenApiRequest request = new com.aliyun.teaopenapi.models.OpenApiRequest().setBody(body);
        java.util.Map<String, ?> resp = client.callApi(params, request, runtime);
        com.aliyun.teaconsole.Client.log(com.aliyun.teautil.Common.toJSONString(resp));
    }
}

Replace global-eos-test1 with your bucket name.

Step 2: Upload an object

Object operations are fully compatible with the OSS SDK. Use the OSS SDK with the EOS endpoint (eos.aliyuncs.com) instead of an OSS regional endpoint.

package com.aliyun.sample;

import com.aliyun.oss.ClientException;
import com.aliyun.oss.OSS;
import com.aliyun.oss.common.auth.*;
import com.aliyun.oss.OSSClientBuilder;
import com.aliyun.oss.OSSException;
import com.aliyun.oss.model.*;

import java.io.ByteArrayInputStream;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Use the EOS endpoint, not an OSS regional endpoint.
        String endpoint = "http://eos.aliyuncs.com";

        // Read credentials from environment variables: OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
        EnvironmentVariableCredentialsProvider credentialsProvider =
                CredentialsProviderFactory.newEnvironmentVariableCredentialsProvider();

        OSS ossClient = new OSSClientBuilder().build(endpoint, credentialsProvider);

        try {
            String bucketName = "global-eos-test1";    // Replace with your bucket name
            String objectName = "demoTestObject.txt";  // Replace with your object key
            String content = "this is demo";

            PutObjectRequest putObjectRequest = new PutObjectRequest(
                    bucketName, objectName, new ByteArrayInputStream(content.getBytes()));
            ossClient.putObject(putObjectRequest);

        } catch (OSSException oe) {
            System.out.println("Request reached EOS but was rejected: " + oe.getErrorMessage());
            System.out.println("Error code: " + oe.getErrorCode());
            System.out.println("Request ID: " + oe.getRequestId());
        } catch (ClientException ce) {
            System.out.println("Client-side error (e.g., network issue): " + ce.getMessage());
        } finally {
            if (ossClient != null) {
                ossClient.shutdown();
            }
        }
    }
}

For more upload methods (multipart upload, append upload, and streaming), see Simple upload.

Step 3: Download an object

Object download is also fully compatible with the OSS SDK. Use the same eos.aliyuncs.com endpoint and OSS SDK client as in Step 2.

For download methods including streaming and range downloads, see Download objects. To generate presigned URLs for authorized access, see Authorize access.

API compatibility reference

The table below lists which operations are available through EOS's own OpenAPI and which are compatible with OSS SDKs.

• EOS OpenAPI: Yes — call using ENS SDK (endpoint: ens.aliyuncs.com)

• OSS-compatible: Yes — call using OSS SDK (endpoint: eos.aliyuncs.com)

ListBuckets and PutBucket are available through the EOS OpenAPI but are not compatible with the OSS SDK. Always use the ENS SDK for these two operations.

What's next

• Integration overview — full EOS API reference and ENS SDK setup

• OSS SDK overview — OSS SDK documentation for all object operations

• Authorization management — configure fine-grained RAM permissions