# idaas-instance

Part of **IDAAS**

# IDaaS Instance and Network Management

## Capabilities Overview

| Sub-capability | Calling Mode | Description |
|----------------|--------------|-------------|
| Manage Instances | Synchronous | Create, update, delete, list, and retrieve details of IDaaS instances. |
| Manage Instance Licenses | Synchronous | Create trial licenses, renew free license end times, and retrieve license information. |
| Check Instance Status | Synchronous | Verify instance deletability and check module status for operational health. |
| Manage Instance Configuration | Synchronous | Get and set instance control configuration, globalization settings, and quotas. |
| Generate Upload Credentials | Synchronous | Generate authentication credentials for uploading files to the instance. |
| List Regions | Synchronous | Retrieve a list of supported or available regions for IDaaS instances. |
| Manage Network Resources | Synchronous | Delete network access endpoints and zones, and update network zone descriptions. |
| Manage Network Access Endpoints | Synchronous | Create, delete, update, and retrieve network access endpoints and their configurations. |
| Manage Network Zones | Synchronous | Create, delete, update, and retrieve network security zones. |
| List Network Access Paths | Synchronous | Retrieve a list of available network access paths. |
| List Network Access Endpoints | Synchronous | Retrieve a list of all network access endpoints. |
| Update Network Access Endpoint | Synchronous | Update the name of a network access endpoint. |

## API Calling Patterns

### Authentication
Use Bearer Token authentication with your Alibaba Cloud API key.

- Header format: `Authorization: Bearer <your_api_key>`
- Environment variable: `DASHSCOPE_API_KEY`
- While other authentication methods may exist, Bearer Token is the recommended and most commonly used method across IDaaS APIs.

### Service Endpoint
The IDaaS Instance and Network Management APIs use region-specific endpoints:

- Base URL pattern: `https://eiam.{region}.aliyuncs.com`
- Common regions: `cn-hangzhou`, `cn-shanghai`, `cn-shanghai`

Some APIs also support global endpoints:
- China: `https://api.aliyun.com/api/Eiam/2021-12-01/`
- International: `https://api.alibabacloud.com/api/Eiam/2021-12-01/`

### Synchronous API Pattern
All operations in this domain follow a synchronous request-response pattern:

1. Send an HTTP request (GET, POST) to the appropriate endpoint with required parameters
2. Include the `Authorization: Bearer <your_api_key>` header
3. Receive an immediate JSON response with results or error details
4. Parse the response to extract relevant fields (e.g., `InstanceId`, `RequestId`)

No polling or streaming is required as all operations complete within the initial request.

## Parameter Reference

### Manage Instances

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true* | - | - | The ID of the instance. (*Required for update/delete/get operations) |
| Description | string | false | - | max 128 characters | The description of the instance. |
| PageNumber | integer | false | - | - | The page number for paginated results. |
| PageSize | integer | false | - | - | The number of entries per page. |
| InstanceIds | array | false | - | - | A list of instance IDs to filter results. |
| Status | string | false | - | one of: creating, running | The instance status to filter by. |

### Manage Instance Licenses

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true | - | - | The ID of the IDaaS instance. |

### Check Instance Status

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true | - | - | The ID of the EIAM instance. |
| ModuleKey | string | true | - | - | The identifier of the primary module. |
| FeatureKey | string | false | - | - | The identifier of the secondary module. |
| SubFeatureKey | string | false | - | - | The identifier of the tertiary module. |

### Manage Instance Configuration

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true | - | - | The instance ID. |
| QuotaKey | string | true* | - | - | The quota type. (*Required for GetInstanceQuota) |
| Language | string | true* | - | Example values: zh-Hans-CN, en-US | The language of the instance. (*Required for SetInstanceGlobalizationConfig) |
| TimeZone | string | true* | - | Example values: Asia/Shanghai, UTC | The time zone of the instance. (*Required for SetInstanceGlobalizationConfig) |
| ControlElements | array<object> | false | - | - | The control items to configure for the instance. |

### Generate Upload Credentials

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true | - | - | The instance ID. |
| Type | string | false | - | - | The file type. |
| Purpose | string | false | - | - | The purpose of the file. |

### Manage Network Resources

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true | - | - | The instance ID. |
| NetworkAccessEndpointId | string | true* | - | - | Network Access Endpoint ID. (*Required for endpoint operations) |
| NetworkZoneId | string | true* | - | - | The ID of the network zone. (*Required for zone operations) |
| Description | string | true* | - | - | The new description of the network zone. (*Required for UpdateNetworkZoneDescription) |
| ClientToken | string | false | - | - | The client token used to ensure idempotence of the request. |

### Manage Network Access Endpoints

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true | - | - | The region ID of the VPC. |
| NetworkAccessEndpointName | string | true | - | - | Private network endpoint name. |
| VpcId | string | true | - | - | The ID of the VPC. |
| VpcRegionId | string | true | - | - | The region ID of the outbound VPC. |
| VSwitchIds | array | false | - | - | The IDs of vSwitches. |

### Manage Network Zones

| Parameter | Type | Required | Default | Constraints | Description |
|-----------|------|----------|---------|-------------|-------------|
| InstanceId | string | true | - | - | The ID of the EIAM instance. |
| NetworkZoneName | string | true | - | - | The name of the network zone. |
| Description | string | false | - | - | The description of the network zone. |
| NetworkZoneType | string | true | - | one of: arn:alibaba:idaas:network:zone:classic, arn:alibaba:idaas:network:zone:vpc | The type of the network zone. |
| Ipv4Cidrs | array | false | - | max length 100 entries | The IPv4 CIDR blocks of the network zone. |
| Ipv6Cidrs | array | false | - | max length 100 entries | The IPv6 CIDR blocks of the network zone. |
| VpcId | string | false | - | - | The ID of the VPC. |
| ClientToken | string | false | - | max length 64 characters | The idempotency token. |

## Code Examples

### Create Instance - Python - All Regions

```python
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest

client = AcsClient(
    access_key_id='your-access-key-id',
    access_key_secret='your-access-key-secret',
    region_id='cn-hangzhou'
)

request = CommonRequest()
request.set_domain('eiam.aliyuncs.com')
request.set_version('2021-12-01')
request.set_action_name('CreateInstance')
request.add_query_param('Description', 'instance_for_test')

response = client.do_action_with_exception(request)
print(response.decode('utf-8'))
```

### List Instances - Python - All Regions

```python
import requests

url = "https://api.aliyun.com/api/Eiam/2021-12-01/ListInstances"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
params = {
    "PageNumber": 1,
    "PageSize": 20,
    "Status": "running"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

### Create Network Zone - Python - All Regions

```python
import dashscope

from dashscope.api import get_api_key

# Set your API key
api_key = get_api_key()

# Define parameters
params = {
    'InstanceId': 'idaas_ue2jvisn35ea5lmthk267xxxxx',
    'NetworkZoneName': 'IPV4Test',
    'Description': 'Test description',
    'NetworkZoneType': 'arn:alibaba:idaas:network:zone:classic',
    'Ipv4Cidrs': ['0.0.0.0/0'],
    'ClientToken': 'client-token-example'
}

# Call the API
response = dashscope.Eiam.create_network_zone(**params)

# Print response
print(response)
```

### Generate Upload Credentials - Bash - All Regions

```bash
curl -X POST https://api.alibabacloud.com/api/Eiam/2021-12-01/GenerateUploadAuth \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "InstanceId": "idaas_111ccc11xxxx",
    "Type": "image",
    "Purpose": "user_import"
  }'
```

### List Regions - Python - All Regions

```python
import json
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest

client = AcsClient(
    access_key_id='your-access-key-id',
    access_key_secret='your-access-key-secret',
    region_id='cn-hangzhou'
)

request = CommonRequest()
request.set_domain('eiam.aliyuncs.com')
request.set_version('2021-12-01')
request.set_method('POST')
request.set_uri_pattern('/ListEiamRegions')

response = client.do_action_with_exception(request)
print(response.decode('utf-8'))
```

### Update Instance Description - Curl - All Regions

```bash
curl -X POST https://eiam.cn-shanghai.aliyuncs.com/api/v1/instances/updateDescription \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"InstanceId":"idaas_ue2jvisn35ea5lmthk267xxxxx","Description":"Used in the production environment."}'
```

### Get Network Zone Details - Python - All Regions

```python
import requests

url = "https://api.alibabacloud.com/api/Eiam/2021-12-01/GetNetworkZone"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
params = {
    "InstanceId": "idaas_ue2jvisn35ea5lmthk267xxxxx",
    "NetworkZoneId": "network_11111"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())
```

### List Network Access Endpoints - Python - All Regions

```python
import requests
import json

# Replace with your actual credentials
API_KEY = 'your-api-key'
INSTANCE_ID = 'idaas_ue2jvisn35ea5lmthk267xxxxx'

url = f'https://eiam.cn-hangzhou.aliyuncs.com/api/v1/ListNetworkAccessEndpoints'
headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}
params = {
    'InstanceId': INSTANCE_ID,
    'MaxResults': 20
}

response = requests.get(url, headers=headers, params=params)
if response.status_code == 200:
    data = response.json()
    print(json.dumps(data, indent=2))
else:
    print(f'Error: {response.status_code} - {response.text}')
```

## Response Format

```json
{
  "RequestId": "0441BD79-92F3-53AA-8657-F8CE4A2B912A",
  "InstanceId": "idaas_wj5htncdvoc4q5xxxxxxxxx"
}
```

**Key Fields**:
- `RequestId` — Unique identifier for the API request, useful for troubleshooting
- `InstanceId` — Unique identifier for the created or retrieved IDaaS instance
- `Instance.Status` — Current operational status of the instance (e.g., "running")
- `Instance.Description` — User-provided description of the instance
- `Instance.DefaultEndpoint.Endpoint` — Primary access endpoint for the instance
- `License.LicenseStatus` — Validity status of the instance license
- `CheckInstanceResult.Deletable` — Boolean indicating if the instance can be safely deleted
- `Module.ModuleStatus` — Status of a specific module feature ("enabled" or "disabled")

## Error Handling

| Error Code | Description | Recommended Action |
|------------|-------------|-------------------|
| 400 | Invalid input parameters. Check the request body for missing or malformed fields. | Validate all parameters against the API specification and correct formatting issues. |
| 403 | Access denied. Ensure the user has the required permissions (e.g., eiam:CreateInstance). | Verify your RAM policy includes the necessary permissions for the requested operation. |
| 429 | Too many requests. Rate limiting is enforced; reduce request frequency. | Implement exponential backoff and respect the 100 QPS limit per account. |
| 500 | Internal server error. Retry the request after a short delay. | Wait briefly and retry the request; contact support if the issue persists. |
| InvalidInstanceId.NotFound | The specified instance ID does not exist. Verify the instance ID and try again. | Double-check the instance ID and ensure it belongs to your account. |
| InstanceInUse | The instance is currently in use and cannot be deleted. | Release all associated resources before attempting deletion. |
| UnauthorizedOperation | You do not have permission to perform this operation. | Check your RAM policy and ensure you have the required permissions. |
| ResourceNotFound | The specified resource could not be found. | Verify the resource ID and ensure it exists in your account. |
| Throttling | Too many requests have been sent. Reduce the request frequency or wait before retrying. | Implement rate limiting in your client code to stay under 100 QPS. |

### Rate Limits & Retry
- Standard rate limit: 100 QPS per account across most APIs
- Some operations have additional constraints (e.g., 10 concurrent operations for DeleteNetworkAccessEndpoint)
- Implement exponential backoff for retries when encountering 429/Throttling errors
- Respect the Retry-After header if provided in error responses

## Requirements

- SDK package: `aliyun-sdk>=3.0.0` or `dashscope>=1.14.0` (depending on the specific API)
- Environment variable setup: `export DASHSCOPE_API_KEY=your_api_key`
- Python version: 3.6+ (for Python SDK examples)
- For curl examples: standard Unix/Linux environment with curl and jq installed

## FAQ

Q: How do I authenticate my API requests to IDaaS?
A: Use Bearer Token authentication by including the header `Authorization: Bearer YOUR_API_KEY` in all requests. Store your API key securely in the `DASHSCOPE_API_KEY` environment variable.

Q: What regions are supported for IDaaS instances?
A: Commonly supported regions include `cn-hangzhou`, `cn-shanghai`, and `cn-shanghai`. Use the `ListRegions` or `ListEiamRegions` API to get the complete and up-to-date list of available regions.

Q: Can I delete an IDaaS instance that's currently in use?
A: No, you must first verify deletability using the `CheckInstanceForDelete` API. If `Deletable` returns false, review the `RestrictScenarios` to understand what resources need to be released first.

Q: How are IDaaS API calls billed?
A: Most API operations are billed per request with a free tier of 1000 calls per month. Instance creation/deletion may have different billing models (e.g., per-instance-hour). Check the specific pricing details for each operation.

Q: What's the difference between Network Zones and Network Access Endpoints?
A: Network Zones define IP address ranges or VPCs from which access is allowed/restricted, while Network Access Endpoints provide secure connectivity to private resources through VPC configurations.

## Pricing & Billing

### Billing Model
Most operations follow a per-request billing model, while instance creation uses per-instance-hour billing.

### Price Reference

| Tier/Model | Input Price | Output Price |
|------------|-------------|--------------|
| Standard | 0.02 / | 0.02 / |
| standard | 0.001 / | 0.001 / |
| standard | 0.0001 / | 0.0001 / |
| Free Edition Renewal | |
| default | |

### Free Tier
- Instance operations: 100 
- API calls: 1000 (most operations)
- Trial license operations: 

### Usage Limits
- Rate limits: 100 QPS per account (standard)
- Instance quota: 10 
- Description length: 256 
- Network zone entries: max length 100 entries for CIDR blocks

### Billing Notes
- Instances are billed per hour from creation until deletion
- API calls are billed per request regardless of success/failure
- Free tier resets monthly
- Failed requests still count toward rate limits and free tier usage