2025.3.4
首页 ▸ Integrations ▸

Google Calendar

The Google Calendar integration allows you to connect your Google Calendar to Home Assistant. The integration adds calendar entities that are shown on the Calendar dashboard, and can be used for automations based on any event, or limited to specific matching criteria.

Prerequisites

You need to configure developer credentials to allow Home Assistant to access your Google Account. The current recommended approach is to create Web Auth credentials for Google Calendar since the same credentials work for all Google integrations. Previously, this integration only supported Device Auth and those credentials are no longer recommended. You can continue to use Device Auth credentials but they will only work with Google Calendar.

情景 1：您已经拥有凭据

在这种情况下，您需要做的就是启用 API：

  1. 转到 Google 开发者控制台 Google Calendar API 。
  2. 确认项目并 启用 API。
  3. 按照 配置 部分中描述的步骤继续进行。

情景 2：您尚未设置凭据

在这种情况下，您需要先生成一个客户端密钥：

生成客户端 ID 和客户端密钥

本节说明如何在 Google 开发者控制台 上生成客户端 ID 和客户端密钥。

  1. 首先，转到 Google 开发者控制台以启用 Google Calendar API 。
  2. 选择 创建项目，输入项目名称并选择 创建。
  3. 启用 Google Calendar API。
  4. 导航到 API 和服务（左侧边栏） > 凭据。
  5. 在左侧边栏，选择 OAuth 同意屏幕。
    • 选择 外部 并 创建。
    • 将 应用名称（请求同意的应用程序名称）设置为您想要的任何名称，例如 Home Assistant。
  6. 您需要选择一个 支持电子邮件。
    • 从下拉菜单中选择您的电子邮件地址。
  7. 在 开发者联系信息 下，输入您的电子邮件地址（可以与上面的相同）。
  8. 向下滚动并选择 保存并继续。
    • 您不需要在这里填写其他任何内容。添加此页面的其他信息（如应用标志）可能会触发 Google 的额外审核过程，并导致设置延迟几天。
  9. 然后，您将自动进入 范围 页面。
    • 您不需要在此处添加任何范围。选择 保存并继续 以移至 测试用户 页面。
    • 您不需要在 测试用户 页面添加任何内容。选择 保存并继续，这将带您到 摘要 页面。
    • 选择 返回仪表板。
  10. 重新选择 OAuth 同意屏幕 并在 发布状态 下选择 发布应用。
    • 否则您的凭据将每7天到期。
  11. 确保 发布状态 设置为 在生产中。
  12. 在左侧边栏中，选择 凭据，然后选择 创建凭据（在屏幕顶部），再选择 OAuth 客户端 ID。
  13. 将 应用程序类型 设置为 Web 应用程序，并给这个凭据集命名（例如 “Home Assistant Credentials”）。
  14. 将 https://my.home-assistant.io/redirect/oauth 添加到 授权重定向 URI 中，然后选择 创建。
    • 这不是占位符。它是必须使用的 URI。
  15. 然后，您将看到一个弹出窗口，显示 OAuth 客户端已创建，显示 您的客户端 ID 和 您的客户端密钥。
    • 请记下这些（例如，将其复制并粘贴到文本编辑器中），因为您稍后需要它们。
    • 记下这些字符串后，选择 确定。
    • 如果您在任何时候需要再次查找这些凭据，请导航到 API 和服务 > 凭据，您将在 OAuth 2.0 客户端 ID 下看到 Home Assistant Credentials（或您在上一步中命名的任何名称）。
    • 要查看 客户端 ID 和 客户端密钥，请选择铅笔图标。这将带您进入这些凭据的设置页面，信息将在页面右侧显示。
  16. 恭喜您！您现在是客户端密钥的保管者。将其保存在您的宝藏箱中。在大多数情况下，您的新凭据将在几分钟内激活。然而，Google 表示在某些情况下激活可能需要多达五小时。

配置

要将 Google Calendar integration 添加到您的 Home Assistant 实例中，请使用此 My 按钮：

手动配置步骤

如果上述 My 按钮不起作用，您也可以手动执行以下步骤：

集成设置将接下来给您提供进入 应用凭证（OAuth 客户端 ID 和客户端密钥）的说明，并授权 Home Assistant 连接到 Google Calendar。

OAuth 和设备授权步骤

  1. 继续执行选择您想要授权的帐户的步骤。

  2. 注意：您可能会收到一条消息，告知您该应用尚未经过验证，您需要确认才能继续。

  3. 现在您可以看到您授权 Home Assistant 访问的详细信息，底部有两个选项。选择 继续。

  4. 页面现在将显示 将账户链接到 Home Assistant 吗？，请注意 您的实例 URL。如果不正确，请参考 我的 Home Assistant。如果一切正常，请选择 链接账户。

  5. 您可以关闭窗口，然后返回 Home Assistant，在那里您应该会看到来自 Home Assistant 的 成功！ 消息。

Troubleshooting

If the setup process fails and you see an error message such as Authentication code expired, please try again you may want to try the flow again. You may also check the logs for additional error messages that may indicate a misconfiguration such as an invalid client id or secret.

If you have an error with your credentials, you can delete them in the application credentials user interface.

Video tutorial

This video tutorial explains how to set up Google Calendar in Home Assistant and how you can trigger an automation based on a calendar event.

Calendar entities

Each Google Calendar from My Calendars (more info) is represented as a calendar entity in Home Assistant.

For example, your calendar named Personal is created as entity calendar.personal. You may rename an entity, or disable any entities which you don’t need.

Calendar event automations

Individual Calendar Events are what is powering automations such as:

  • Turn on a light at the start of the event named Front Yard Light
  • Send a notification 5 minutes before the start of any event
  • Stop the media player 30 minutes after the end of the event named Exercise.

See calendar automations for an overview, and read more about calendar trigger variables for the available information you can use in a condition or action such as the event summary, description, location and more.

Calendar entity attributes

The calendar entity has additional attributes related to a single next upcoming event.

Tip

Using the entity state and attributes is more error prone and less flexible than using Calendar Automations. The calendar entity itself may only track a single upcoming active event and can’t handle multiple events with the same start time, or overlapping events.

Attributes
  • all_day: true/false if this is an all day event. Will be false if there is no event found.
  • message: The event summary.
  • description: The event description.
  • location: The event location.
  • start_time: Start time of event.
  • end_time: End time of event.

Action google.create_event

You can use the google.create_event action to create a new calendar event in a calendar.

Create event action details

Note

This will only be available if you have given Home Assistant read-write access in configuration options.

A calendar target is selected with a Target Selector and the data payload supports the following fields:

Data attribute Optional Description Example
summary no Acts as the title of the event. Bowling
description yes The description of the event. Birthday bowling
start_date_time yes The date and time the event should start. 2019-03-10 20:00:00
end_date_time yes The date and time the event should end. 2019-03-10 23:00:00
start_date yes The date the whole day event should start. 2019-03-10
end_date yes The date the whole day event should end. 2019-03-11
in yes Days or weeks that you want to create the event in. “days”: 2
location yes The location of the event. Bowling center

Important

You either use start_date_time and end_date_time, or start_date and end_date, or in.

This is a full example of an action in YAML:

action: google.create_event
target:
  entity_id: calendar.device_automation_schedules
data:
  summary: "Example"
  start_date: "2022-10-1"
  end_date: "2022-10-2"

More configuration

More Configuration

Warning

It is not recommended to new users to use these settings as they are not compatible with other Home Assistant features, but this documentation is available for existing users.

The integration supports additional configuration from a file google_calendars.yaml which is available for existing users before version 2022.06. This file is no longer automatically populated.

Configuration Variables

Looking for your configuration file?
cal_id string Required

The Google generated unique id for this calendar.

Default:

DO NOT CHANGE THE DEFAULT VALUE

entities list Required

Yes, you can have multiple sensors for a calendar!

device_id string Required

The name that all your automations/scripts will use to reference this device.

name string Required

What is the name of your sensor that you’ll see in the frontend.

search string (Optional)

If set will only trigger for matched events.

offset string (Optional, default: !!)

A set of characters that precede a number in the event title for designating a pre-trigger state change on the sensor. This should be in the format of HH:MM or MM.

ignore_availability boolean (Optional, default: true)

Should we respect free/busy flags?