mitol-django-google-sheets 2024.7.3

mitol-django-google-sheets

这是开源学习Django Google Sheets核心库。它的目的是围绕Google Sheets包装核心功能，以便在更具体的库中进行消费。

设置

pip install mitol-django-google-sheets

添加Google Sheets应用

INSTALLED_APPS = [
    ...
    "mitol.google_sheets.apps.GoogleSheetsApp",
]

配置

首先，从Drive收集一些ID类型的值

1. 您在上面创建的Web应用程序凭据的“客户端ID”和“客户端密钥”值（API控制台凭据部分）

2. 您的API项目ID，您可以在Google Cloud Platform > IAM & Admin > 设置 > 项目ID中找到。例如：my-api-project-1234567890123

3. 请求工作表的Drive文件ID。您可以通过从Drive打开工作表并检查URL来找到这些ID。复制注册代码请求工作表的ID。

   示例

   https://docs.google.com/spreadsheets/d/THIS_IS_THE_ID_VALUE/edit#gid=0

如果不明显，请移除实际值的角度括号（<>）。

MITOL_GOOGLE_SHEETS_DRIVE_CLIENT_ID=<Client ID from step 1>
MITOL_GOOGLE_SHEETS_DRIVE_CLIENT_SECRET=<Client secret from step 1>
MITOL_GOOGLE_SHEETS_DRIVE_API_PROJECT_ID=<Project ID from step 2>
MITOL_GOOGLE_SHEETS_PROCESSOR_APP_NAME=<Name of the app processing the request>
MITOL_GOOGLE_SHEETS_ENROLLMENT_CHANGE_SHEET_ID=<Change of enrollment request sheet ID from step 3>
MITOL_GOOGLE_SHEETS_PROCESS_ONLY_LAST_ROWS_NUM=<Optional: the number of rows to process from the bottom>

用法

此库的用法仅限于与mitol-google-sheets-refunds或mitol-google-sheets-deferrals结合使用。

以下是创建退款请求的示例工作流程

1. 填写并提交工作表请求表单。这将向注册代码请求工作表的第一张工作表添加一行。
2. 运行管理命令以处理工作表：./manage.py process_refund_requests -i "<spreadsheet id>"。这将更新您添加的行的“处理日期”列。
3. 在工作表中检查请求的状态。

与mitol-google-sheets集成

将其添加到您的设置文件中

# import_settings_module, imports the default settings defined in mitol-google-sheets app
from mitol.common.envs import import_settings_modules
import_settings_modules(globals(), "mitol.google-sheets.settings.google_sheets")

创建工作表配置，例如

from mitol.google_sheets.utils import SingletonSheetConfig
class RefundRequestSheetConfig(SingletonSheetConfig, subclass_type=<type_of_spreadsheet>):
    """Metadata for the refund request spreadsheet"""
    def __init__(self):
        self.sheet_type = "<type_of_spreadsheet>"
        self.sheet_name = "Refund Request sheet"
        self.worksheet_type = WORKSHEET_TYPE_REFUND
        self.worksheet_name = "Refunds"

继承SingletonSheetConfig将允许你在基类中注册你的电子表格类型。这可以通过运行SingletonSheetConfig.get_subclass_by_type(<type_of_sheet>)根据电子表格的类型确定适当的配置类。这在各种任务和管理命令中使用，例如你想在所有当前注册的电子表格上设置文件监视。

在你的urls.py

urlpatterns = (
    [
        ...
        path("", include("mitol.google_sheets.urls")),
    ]
)

开发者设置

本指南包含了在您自己的开发环境中修改sheets功能的说明。

以下是在开始修改此功能之前只需完成一次的步骤。

1) 依赖项

1. 一个谷歌账号
2. ngrok – 这是一个使您的本地主机可以访问更广泛互联网的工具。这对于验证您本地运行的xPRO应用程序以更改您的Google Drive文件是必要的。如果您的应用程序已部署在某个地方或您有等效的工具，ngrok不是必需的，但以下说明假设其使用。

2) 配置凭据和权限

1. 在谷歌云平台中创建一个API项目：https://console.cloud.google.com/home/dashboard
2. 为该项目创建网络应用程序凭据
   1. 访问谷歌开发者控制台的凭据部分：https://console.developers.google.com/apis/credentials
   2. 点击创建凭据 > OAuth客户端ID
   3. 选择“Web应用程序”，为凭据提供一个直观的名称（如“xPRO auth”等），然后提交。
3. 为您的项目启用驱动器API
   1. 访问API控制台：https://console.developers.google.com/apis/library
   2. 从页面顶部的下拉菜单中选择您的谷歌云平台项目。
   3. 找到驱动器API，点击它，然后启用它。

3) 复制xPRO驱动器项目文件夹

xPRO驱动器文件夹应该包含以下元素

1. 电子表格，用于为我们服务的每种“请求”类型。截至2020年7月，这包括注册代码请求电子表格和注册更改请求电子表格。
2. 表单，用于向这些电子表格提交新请求。截至2020年7月，这包括注册代码请求表单、退款请求表单和延期请求表单。
3. 一个文件夹，这是我们生成的注册代码分配电子表格的目标。

此文件夹的内容应从“模板”文件夹复制到您本地驱动器中的一个文件夹。在MIT共享驱动器上有一个模板文件夹，或者您可以请另一位开发者分享一个。请通过与团队成员聊天或发邮件来找到其中一个模板文件夹。请与团队成员联系，让他们指给您一个模板文件夹。一旦您可以访问模板文件夹，请按照以下步骤创建自己的副本

1. 在您的本地驱动器中创建一个文件夹。命名为“Local xPRO Enrollments”之类的名称。
2. 为分配电子表格创建一个空子文件夹。命名为“Local Assignment Sheets”之类的名称。
3. 在模板文件夹中，选择电子表格（NOT表单或任何文件夹），并复制它们。
   • 注意：这将自动创建表单的副本，因为表单已经链接到电子表格。这是故意的。
   • 另外注意：这些电子表格每个都已经有了一个测试响应，并且应该出现在主工作表中。请保留这些测试响应。
4. 选择复制的电子表格和表单，并将它们移动到您上面创建的xPRO enrollments文件夹中。

完成时，您的驱动器文件夹应如下所示

4) 添加初始设置

使用以上以MITOL_GOOGLE_SHEETS...开头的设置更新您的.env文件。

认证

您的本地xPRO需要权限才能读取/写入您的驱动器。这可以通过使用ngrok的OAuth来完成。

1. 使用此应用程序的nginx端口运行ngrok：ngrok http 8013
2. 访问Google开发者控制台的凭证部分： https://console.developers.google.com/apis/credentials，选择您的身份验证客户端，并更新授权重定向URI（如有更改）。
3. 开始域名验证
   1. 访问网站管理员工具主页： https://www.google.com/webmasters/verification/home?hl=en
   2. 输入ngrok公开的HTTPS URL（包括协议在内的完整URL）
   3. 选择备用方法 > HTML标签身份验证，并复制标签的“content”属性值（仅值，不是完整的HTML标签）
4. 更新您的.env文件

<your_app_name>_BASE_URL=<Full ngrok HTTPS URL, including protocol>
GOOGLE_DOMAIN_VERIFICATION_TAG_VALUE=<"content" attribute value from step 2.iii>

例如

MITX_ONLINE_BASE_URL= https://12345abc6789.ngrok.io
GOOGLE_DOMAIN_VERIFICATION_TAG_VALUE=ETRM2VjAZ3BF52L_ait6r...

4. （重新）启动容器
5. 当容器完全运行时，在域名验证页面点击“验证”。这应该会成功。
6. 添加Google API控制台配置（API控制台链接）
   1. 域名验证（链接）：添加ngrok域名（例如：12345abc6789.ngrok.io）
   2. OAuth同意屏幕（链接）
      1. 在“测试用户”下点击“添加用户”，添加您的电子邮件地址
      2. 点击“编辑应用”
      3. 在“授权域名”部分添加一个域名。按Enter键添加。
      4. 在底部点击“保存”
   3. 凭证（链接）
      1. 在OAuth 2.0客户端ID部分点击您的网络应用凭证名称
      2. 在“授权重定向URI”部分，点击“添加URI”，并输入附加了/sheets/auth-complete/的ngrok HTTPS URL，例如：https://12345abc6789.ngrok.io/sheets/auth-complete/
      3. 点击“保存”
7. 使用ngrok HTTP URL（例如：http://12345abc6789.ngrok.io/admin/）通过Django管理登录xPRO
8. 验证/授权应用
   1. 使用ngrok HTTP URL（例如：http://12345abc6789.ngrok.io/sheets/admin/）导航到电子表格管理页面
   2. 点击“授权”按钮并完成Google OAuth流程
      • 注意：在选择用户后，您将遇到一个警告页面。要继续，请点击“高级”，然后点击底部的“转到 <url>”链接

在设置Google电子表格和请求表单时

您需要将退款表单响应链接到输出到电子表格。您可以通过打开表单并选择响应->设置->选择响应目标->选择现有电子表格来实现。填写表单时，它将创建一个新的工作表，称为“表单响应 1”等。您可以重命名此标签为“退款表单响应”。在“退款表单响应”工作表中，请确保“时间戳”列格式设置为“日期”而不是“日期时间”。主Google工作表通过以下查询由“退款响应”工作表更新

={QUERY({'Refund Form Response'!A2:G, ARRAYFORMULA(if(isblank('Refund Form Response'!A2:A),"",ROW('Refund Form Response'!A2:G)))},"SELECT Col8, Col1, Col3, Col4, Col2, Col5, Col6, Col7",0)}

将此查询添加到第一行第一列（4:A）。