---
title: 查询日历与日程
description: 获取用户日历，在 UTC 时间范围内查询日程并读取详情。
sidebar_label: 查询日历与日程
sidebar_position: 6
---

# 查询日历与日程

日程查询需要先确定用户和日历，再使用 UTC 时间范围查询日历视图。循环日程可能展开为多次实例，调用方应保留日历 ID 与日程 ID。

## 调用顺序

1. 调用[查询日历列表](/api/alimailpb-alimail-mailagent-open-calendar-service-list-calendars)。
2. 选择目标日历 ID，调用[查询时间范围内的日程](/api/alimailpb-alimail-mailagent-open-event-service-event-view)。
3. 按 `nextCursor` 读取完整视图。
4. 使用日历 ID 和日程 ID 调用[查询日程详情](/api/alimailpb-alimail-mailagent-open-event-service-get-event)。

## Python 示例

```python runtimeApiEndpoint
import requests

API_BASE = "https://alimail-cn.aliyuncs.com"


def list_events(
    access_token: str,
    mailbox: str,
    calendar_id: str,
    start_time: str,
    end_time: str,
) -> list[dict]:
    headers = {"Authorization": f"Bearer {access_token}"}
    events = []
    cursor = ""
    while True:
        response = requests.get(
            f"{API_BASE}/v2/users/{mailbox}/calendars/{calendar_id}/eventsview",
            headers=headers,
            params={
                "startTime": start_time,
                "endTime": end_time,
                "cursor": cursor,
            },
            timeout=15,
        )
        response.raise_for_status()
        payload = response.json()
        events.extend(payload.get("events", []))
        if not payload.get("hasMore"):
            return events
        cursor = payload["nextCursor"]
```

时间参数使用 ISO 8601 UTC 格式，例如 `2026-07-01T00:00:00Z`。展示给用户时再转换到目标时区。

参考：[原始示例](https://help.aliyun.com/zh/document_detail/2856495.html)。