如何在自建Django云服务中使用Google HomeGraph API？

官方提供的Firebase示例本质是对HomeGraph API原生接口的封装，对接自有Django服务可以直接跳过Firebase层，直接通过服务账号调用原生接口，具体实现步骤如下：

一、前置依赖配置 #

• 首先在Google Cloud Console中启用HomeGraph API，创建拥有HomeGraph Admin权限的服务账号，下载JSON格式的密钥文件存储到Django服务可访问的路径下，注意不要将密钥文件提交到代码仓库
• Django服务安装Google官方API依赖包：
  pip install google-api-python-client google-auth-httplib2 google-auth-oauthlib

二、核心对接逻辑实现 #

1. 初始化HomeGraph客户端 #

在Django的公共工具模块中封装客户端初始化逻辑，全局复用即可：

import uuid
from google.oauth2 import service_account
from googleapiclient.discovery import build

# 权限范围固定为HomeGraph全权限
SCOPES = ['https://www.googleapis.com/auth/homegraph']
# 替换为你自己的服务账号密钥文件存储路径
SERVICE_ACCOUNT_FILE = '/your/path/service-account-key.json'

# 初始化认证凭证和客户端
credentials = service_account.Credentials.from_service_account_file(
    SERVICE_ACCOUNT_FILE, scopes=SCOPES)
homegraph_client = build('homegraph', 'v1', credentials=credentials)

2. 设备同步接口调用 #

用户在Google Home App完成账号绑定后，你返回SYNC响应的同时必须调用requestSyncDevices接口，触发HomeGraph拉取你侧的设备列表：

def request_sync_devices(django_user_id):
    # django_user_id为你系统内用户的唯一标识，必须和SYNC响应中返回的agentUserId完全一致
    request = homegraph_client.devices().requestSync(
        body={
            "agentUserId": str(django_user_id),
            "async": False
        }
    )
    return request.execute()

3. 设备状态上报接口调用 #

每次用户查询设备状态、执行语音指令完成、或者设备端主动上报状态变更后，都需要调用reportStateAndNotification接口将最新状态同步到HomeGraph，避免Google侧和你侧状态不一致：

def report_device_states(django_user_id, state_payload):
    # state_payload格式必须严格匹配Google智能家居设备schema，键为设备ID，值为对应状态键值对
    body = {
        "requestId": "unique_request_id_"+str(uuid.uuid4()), # 每次请求生成唯一ID即可
        "agentUserId": str(django_user_id),
        "payload": {
            "devices": {
                "states": state_payload
            }
        }
    }
    request = homegraph_client.devices().reportStateAndNotification(body=body)
    return request.execute()

三、关键注意事项 #

• 所有设备的ID、设备类型、支持的trait属性必须和你在Actions on Google控制台配置的完全一致，否则会触发权限错误或同步失败
• 你提供给Google的Fulfillment webhook地址必须支持HTTPS，本地调试可以用ngrok等工具做内网穿透
• 所有HomeGraph API的调用必须在Django后端完成，绝对不要在前端暴露服务账号密钥
• 提前将创建的服务账号添加到你的Actions on Google项目的成员列表中，授予编辑权限即可正常调用接口

内容的提问来源于stack exchange，提问作者Prashant Nath