# rds-edge

Part of **RDS**

# ApsaraDB RDS Edge Function Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| CreateEdgeFunction | Synchronous | Creates an edge function by compressing code into a zip file and uploading it to Supabase Storage. The operation requires an RDS Supabase instance ID and supports optional configuration for OSS storage and environment variables. |
| DeleteEdgeFunction | Synchronous | Deletes an edge function associated with an RDS Supabase instance. This API operation requires the instance name and optionally supports region ID, client token, and edge function name for identification. |
| DescribeEdgeFunctions | Synchronous | Query the list of edge functions or a specified edge function for an ApsaraDB RDS Supabase instance. This API returns detailed information about each edge function, including runtime, resource allocation, URLs, and status. |
| UpdateEdgeFunction | Synchronous | Updates an edge function in ApsaraDB RDS, including code versions, environment variables, and configurations. This API allows modifying the behavior and settings of existing edge functions. |

## API Calling Patterns

### Authentication
Use **Bearer Token** authentication as the primary method.

- Include the header: `Authorization: Bearer <your_api_key>`
- Set the environment variable: `DASHSCOPE_API_KEY`
- Example: `export DASHSCOPE_API_KEY=sk-xxxxxx`

While other Alibaba Cloud authentication methods exist (e.g., AccessKey), the documented examples consistently use Bearer tokens with the `DASHSCOPE_API_KEY` credential.

### Service Endpoint
All APIs use a single global base URL:

```text
https://api.alibabacloud.com/api/RdsAi/2025-05-07
```

This is **not region-specific**—the same endpoint handles all regions. The `RegionId` parameter (when provided) specifies the target region for the operation.

Common regions include: `cn-hangzhou`, `cn-shanghai`, `cn-beijing`.

### Synchronous Request Pattern
All edge function operations follow a **synchronous** pattern:

1. Send a `POST` request to the specific action endpoint (e.g., `/CreateEdgeFunction`)
2. Include parameters as JSON in the request body
3. Provide the `Authorization: Bearer $DASHSCOPE_API_KEY` header
4. Receive a JSON response immediately with result or error
5. Parse the `RequestId`, `InstanceName`, and function-specific fields from the response

No polling or async task tracking is required—operations complete before the HTTP response is returned.

## Parameter Reference

### CreateEdgeFunction / UpdateEdgeFunction

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| RegionId | string | false | — | — | The region ID. |
| InstanceName | string | true | — | — | The ID of the RDS Supabase instance. |
| EdgeFunctionName | string | false | — | — | The name of the function. |
| ClientToken | string | false | — | — | The client token that is used to ensure the idempotence of the request. |
| Code | object | false | — | — | The code parameters. |
| Code.OssBucketName | string | false | — | — | The name of the OSS bucket. |
| Code.OssObjectName | string | false | — | — | The OSS path of a code file. |
| Code.OssType | string | false | — | — | The storage class of the OSS bucket. |
| CustomConfig | object | false | — | — | The configuration parameters of the edge function. |
| CustomConfig.* | string | false | — | — | The configuration of the edge function. |
| Envs | object | false | — | — | The environment variables. |
| Envs.* | string | false | — | — | The environment variable. |

### DeleteEdgeFunction / DescribeEdgeFunctions

| Parameter | Type | Required | Default | Constraints | Description |
|----------|------|----------|---------|-------------|-------------|
| RegionId | string | false | — | — | The region ID. |
| InstanceName | string | true | — | — | The ID of the RDS Supabase instance. |
| EdgeFunctionName | string | false | — | — | The name of the edge function (e.g., `fc-xxxx`). |
| ClientToken | string | false | — | — | The client token that is used to ensure the idempotence of the request. |

## Code Examples

### Create Edge Function - curl - Global

```bash
curl -X POST "https://api.alibabacloud.com/api/RdsAi/2025-05-07/CreateEdgeFunction" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "InstanceName": "ra-supabase-8moov5lxba****",
    "EdgeFunctionName": "my-function",
    "Code": {
      "OssBucketName": "my-bucket",
      "OssObjectName": "code/function.zip"
    },
    "Envs": {
      "ENV_VAR1": "value1"
    }
  }'
```

### Delete Edge Function - curl - Global

```bash
curl -X POST "https://api.alibabacloud.com/api/RdsAi/2025-05-07/DeleteEdgeFunction" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "InstanceName": "ra-supabase-8moov5lxba****",
    "EdgeFunctionName": "ef-****"
  }'
```

### Describe Edge Functions - Python - Global

```python
import os
import requests

url = "https://api.alibabacloud.com/api/RdsAi/2025-05-07/DescribeEdgeFunctions"
headers = {
    "Authorization": f"Bearer {os.getenv('DASHSCOPE_API_KEY')}",
    "Content-Type": "application/json"
}
payload = {
    "InstanceName": "ra-supabase-8moov5lxba****"
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())
```

### Update Edge Function - curl - Global

```bash
curl -X POST "https://api.alibabacloud.com/api/RdsAi/2025-05-07/UpdateEdgeFunction" \
  -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "InstanceName": "ra-supabase-8moov5lxba****",
    "EdgeFunctionName": "ef-****",
    "Envs": {
      "NEW_VAR": "updated_value"
    }
  }'
```

## Response Format

```json
{
  "RequestId": "FE9C65D7-930F-57A5-A207-8C396329****",
  "InstanceName": "ra-supabase-8moov5lxba****",
  "EdgeFunctionName": "ef-****"
}
```

**Key Fields**:
- `RequestId` — Unique identifier for the API request; useful for troubleshooting
- `InstanceName` — The RDS Supabase instance ID associated with the operation
- `EdgeFunctionName` — The name of the affected edge function

For `DescribeEdgeFunctions`, the response includes an `EdgeFunctions` array with additional details:

```json
{
  "RequestId": "FE9C65D7-930F-57A5-A207-8C396329****",
  "InstanceName": "ra-supabase-8moov5lxba****",
  "EdgeFunctions": [
    {
      "EdgeFunctionName": "ef-****",
      "Runtime": "custom.debian12-deno-2.5.6",
      "Cpu": 1,
      "MemorySize": 512,
      "UrlInternet": "https://fc-bfvmoi****.cn-beijing.fcapp.run",
      "UrlIntranet": "https://fc-bfvmoi****.cn-beijing-vpc.fcapp.run",
      "FunctionUrl": "https://fcnext.console.aliyun.com/cn-beijing/functions/fc****",
      "Status": "Running",
      "CreatedTime": "2021-11-12T21:35:03",
      "ModifiedTime": "2025-05-25 10:22:54 +0800"
    }
  ]
}
```

**Key Fields (Describe)**:
- `EdgeFunctions[].EdgeFunctionName` — Function identifier
- `EdgeFunctions[].Runtime` — Execution environment (e.g., Deno version)
- `EdgeFunctions[].Cpu` / `MemorySize` — Allocated compute resources
- `EdgeFunctions[].UrlInternet` / `UrlIntranet` — Public and private invocation URLs
- `EdgeFunctions[].Status` — Current state (`Running`, etc.)
- `EdgeFunctions[].CreatedTime` / `ModifiedTime` — Lifecycle timestamps

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|-------------------|
| 400 | The request uses the same client token as a previous, but non-identical request. Do not reuse a client token with different requests, unless the requests are identical. | Ensure each unique request uses a new `ClientToken`, or reuse the same token only for identical retries. |
| 400 | Current instance status does not support this operation. The operation is not supported in the current instance state. | Check the RDS instance status; wait until it is in an active or stable state before retrying. |
| 400 | Specified group name is not valid. Invalid group name | Verify that any provided names (e.g., function name) conform to naming rules (alphanumeric, hyphens, etc.). |
| 400 | The provided parameter is invalid. Invalid parameter. | Validate all input parameters against the API specification; check for missing required fields or incorrect types. |
| 404 | User does not exist. User does not exist. | Confirm that your Alibaba Cloud account is properly configured and that the `DASHSCOPE_API_KEY` belongs to an active user. |

## Pricing & Billing

### Billing Model
Billing is **per-request**: each successful API call counts as one billable request.

### Price Reference

| Tier | Input Price | Output Price |
|------|-------------|--------------|
| default | 0.001 / | 0.001 / |
| default (Describe) | 0.002 / | 0.002 / |
| default (Update) | 0.002 / | — |

### Free Tier
- Create/Delete: 100 free calls per month
- Describe/Update: No free tier

### Usage Limits
- Create/Delete: 100 QPS
- Describe/Update: Up to 10 requests per second

### Billing Notes
- Each successful call counts as one request. Billing occurs on completion.
- For Describe and Update, there is no minimum usage requirement.

## FAQ

Q: How do I ensure my edge function creation request is idempotent?
A: Include a unique `ClientToken` in your request. If you retry with the same token and identical parameters, the system will return the original result without reprocessing.

Q: Can I deploy code directly, or must I use OSS?
A: The API supports both: you can reference code in an OSS bucket via `Code.OssBucketName` and `Code.OssObjectName`, or (depending on implementation) provide code inline—though the documented examples primarily use OSS.

Q: Why am I getting a 404 "User does not exist" error?
A: This typically means your `DASHSCOPE_API_KEY` is invalid, expired, or belongs to a deleted account. Verify your key and ensure your Alibaba Cloud account is active.

Q: Are edge functions region-specific even though the API endpoint is global?
A: Yes. While the API endpoint is global, the `RegionId` parameter (or the region associated with your RDS instance) determines where the edge function is deployed and executed.

Q: What runtime environments are supported for edge functions?
A: Based on the response example, `custom.debian12-deno-2.5.6` is supported. Check the latest documentation for additional runtimes such as Node.js, Python, or custom containers.