应用程序开发人员 AppFabric 工作效率入门（预览版） - AWS AppFabric
先决条件第 1 步。为提高工作效率 AppFabric 而创建 AppClient第 2 步。对您的应用程序进行身份验证和授权第 3 步。将 AppFabric 用户门户 URL 添加到您的应用程序第 4 步。 AppFabric 用于显示跨应用程序的见解和操作第 5 步。 AppFabric 请求验证您的申请

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

应用程序开发人员 AppFabric 工作效率入门（预览版）

提高 AWS AppFabric 工作效率功能处于预览阶段，可能会发生变化。

本节帮助应用程序开发者将提高 AWS AppFabric 工作效率（预览）集成到他们的应用程序中。 AWS AppFabric 提高生产力使开发人员能够通过跨多个应用程序的电子邮件、日历事件、任务、消息等生成人工智能驱动的见解和操作，从而为用户打造更丰富的应用程序体验。有关支持的应用程序列表，请参阅AWS AppFabric 支持的应用程序。

AppFabric 提高工作效率为应用程序开发者提供了在安全可控的环境中进行构建和实验的权限。当你第一次开始使用提高 AppFabric 工作效率时，你需要创建一个 AppClient 并注册一个测试用户。此方法旨在帮助您了解和测试应用程序与之间的身份验证和通信流 AppFabric。在对单个用户进行测试后，您可以先将申请提交给 AppFabric 进行验证，然后再将访问权限扩展到其他用户（请参阅第 5 步。 AppFabric 请求验证您的申请）。 AppFabric 将在实现广泛采用之前验证应用程序信息，以帮助保护应用程序开发人员、最终用户及其数据，从而为以负责任的方式扩大用户采用率铺平道路。

主题

先决条件

在开始之前，你需要创建一个 AWS 账户。有关更多信息，请参阅 注册获取 AWS 账户。您还需要创建至少一个有权访问下面列出"appfabric:CreateAppClient"的 IAM 策略的用户，该策略允许该用户注册您的应用程序 AppFabric。有关为生产力功能授予权限 AppFabric 的更多信息，请参阅AppFabric 有关生产力 IAM 策略示例。虽然拥有管理用户是有益的，但对于初始设置来说，这不是强制性的。有关更多信息，请参阅 创建具有管理访问权限的用户。

AppFabric 因为在预览期间，只有美国东部（弗吉尼亚北部）才有生产力。在开始以下步骤之前，请确保您位于此区域。

{
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "appfabric:CreateAppClient"
            ],
            "Resource": ["arn:aws:appfabric:*:*:appclient/*"]
        }
    ],
    "Version": "2012-10-17"
}

第 1 步。为提高工作效率 AppFabric 而创建 AppClient

在开始在应用程序中 AppFabric 显示生产力见解之前，您需要创建一个 AppFabric AppClient. 本质上 AppClient 是您提高工作效率 AppFabric 的门户，它充当安全的OAuth应用程序客户端，可实现应用程序与之间的安全通信。 AppFabric当你创建时 AppClient，你会得到一个 AppClient ID，这是一个唯一的标识符，对于确保它 AppFabric 知道它正在与你的应用程序和你的应用程序一起使用至关重要 AWS 账户。

AppFabric 提高工作效率为应用程序开发者提供了在安全可控的环境中进行构建和实验的权限。当你第一次开始使用提高 AppFabric 工作效率时，你需要创建一个 AppClient并注册一个测试用户。此方法旨在帮助您了解和测试应用程序与之间的身份验证和通信流 AppFabric。在对单个用户进行测试后，您可以先将申请提交给 AppFabric 进行验证，然后再将访问权限扩展到其他用户（请参阅第 5 步。 AppFabric 请求验证您的申请）。 AppFabric 将在实现广泛采用之前验证应用程序信息，以帮助保护应用程序开发人员、最终用户及其数据，从而为以负责任的方式扩大用户采用率铺平道路。

要创建 AppClient，请使用 AWS AppFabric CreateAppClient API 操作。如果您需要更新 AppClient 后面的内容，则可以使用 UpdateAppClient API 操作仅更改 redirectURL。如果您需要更改与您的关联的任何其他参数（ AppClient 例如 AppName 或描述），则必须删除 AppClient 并创建一个新参数。有关更多信息，请参阅 CreateAppClient。

你可以使用 CreateAppClient API 使用多种编程语言（包括 Python、Node.js、Java、C#、Go 和 Rust）向 AWS 服务注册应用程序。有关更多信息，请参阅《IAM 用户指南》中的请求签名示例。您需要使用账户签名版本 4 凭证才能执行此 API 操作。有关签名版本 4 的更多信息，请参阅 I AM 用户指南中的签署 AWS API 请求。

请求字段

  • appName-将在用户门户的同意页面上向用户显示的应用程序的 AppFabric 名称。用户意见征求页面要求最终用户允许在您的应用程序中显示 AppFabric 见解。有关同意页面的详细信息，请参阅 第 2 步。同意应用程序显示见解。

  • description - 应用程序的描述。

  • redirectUrls - 授权后要将最终用户重定向到的 URI。您最多可以添加 5 个 redirectUrl。例如，https://localhost:8080。

  • starterUserEmails - 在应用程序通过验证之前允许访问以接收见解的用户电子邮件地址。只允许使用一个电子邮件地址。例如，anyuser@example.com

  • customerManagedKeyIdentifier（可选）- 用于加密数据的客户托管密钥（由 KMS 生成）的 ARN。如果未指定，则将使用 AWS AppFabric 托管密钥。有关 AWS 拥有的密钥 和客户托管密钥的更多信息，请参阅AWS Key Management Service 开发人员指南中的客户密钥和 AWS 密钥。

响应字段

  • appClientArn-包含编号的亚马逊资源名称 (ARN)。 AppClient 例如， AppClient ID 是a1b2c3d4-5678-90ab-cdef-EXAMPLE11111。

  • verificationStatus- AppClient 验证状态。

    • pending_verification-的验证 AppClient仍在进行中 AppFabric。在 AppClient 验证之前，只有一个用户（在中指定starterUserEmails）可以使用 AppClient。用户将在 AppFabric 用户门户中看到一条通知（如中所述）第 3 步。将 AppFabric 用户门户 URL 添加到您的应用程序，表示该应用程序未通过验证。

    • verified-验证过程已成功完成 AppFabric ，现 AppClient 已完全验证。

    • rejected-的验证过程 AppClient 被拒绝 AppFabric。在重新启动并成功完成验证过程之前，其他用户 AppClient 无法使用。

curl --request POST \
  --header "Content-Type: application/json" \
  --header "X-Amz-Content-Sha256: <sha256_payload>" \
  --header "X-Amz-Security-Token: <security_token>" \
  --header "X-Amz-Date: 20230922T172215Z" \
  --header "Authorization: AWS4-HMAC-SHA256 ..." \
  --url https://appfabric.<region>.amazonaws.com/appclients/ \
  --data '{
    "appName": "Test App",
    "description": "This is a test app",
    "redirectUrls": ["https://localhost:8080"],
    "starterUserEmails": ["anyuser@example.com"],
    "customerManagedKeyIdentifier": "arn:aws:kms:<region>:<account>:key/<key>"
}'

如果此操作成功，则该服务将会发送回 HTTP 200 响应。

{
    "appClientConfigSummary": {
        "appClientArn": "arn:aws:appfabric:<region>:<account>:appclient/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
        "verificationStatus": "pending_verification"
    }
}

第 2 步。对您的应用程序进行身份验证和授权

通过建立 OAuth 2.0 授权流程，使您的应用程序能够安全地集成 AppFabric 见解。首先，您需要创建一个授权码，用于验证您的应用程序身份。有关更多信息，请参阅 授权。然后，您将使用此授权码兑换访问令牌，该令牌授予您的应用程序在应用程序中获取和显示 AppFabric见解的权限。有关更多信息，请参阅 令牌。

有关授予应用程序授权权限的更多信息，请参阅 允许访问以授权应用程序。

  1. 要创建授权码，请使用 AWS AppFabric oauth2/authorize API 操作。

    请求字段

    GET https://productivity.appfabric.<region>.amazonaws.com/oauth2/authorize?app_client_id=a1b2c3d4-5678-90ab-cdef-EXAMPLE11111\
redirect_uri=https://localhost:8080&state=a8904edc-890c-1005-1996-29a757272a44

  2. 身份验证后，您将被重定向到指定的 URI，并以查询参数形式返回授权码。例如，其中 code=mM0NyJ9.MEUCIHQQgV3ChXGs2LRwxLtpsgya3ybfPYXfX-sxTAdRF-gDAiEAxX7BYKlD9krG3J2VtprOjVXZ0FSUX9whdekqJ-oampc。

    https://localhost:8080/?code=mM0NyJ9.MEUCIHQQgV3ChXGs2LRwxLtpsgya3ybfPYXfX-sxTAdRF-gDAiEAxX7BYKlD9krG3J2VtprOjVXZ0FSUX9whdekqJ-oampc&state=a8904edc-890c-1005-1996-29a757272a44

  3. 使用 AppFabric oauth2/token API 操作将此授权码交换为访问令牌。

    此令牌用于 API 请求，最初在验证starterUserEmails之前一直有效。 AppClient 验证后，该令牌可用于任何用户。 AppClient 您需要使用账户签名版本 4 凭证才能执行此 API 操作。有关签名版本 4 的更多信息，请参阅 I AM 用户指南中的签署 AWS API 请求。

    请求字段

    响应字段

    • expires_in - 在令牌过期之前多久。默认过期时间为 12 小时。

    • refresh_token - 从初始 /token 请求接收的刷新令牌。

    • token - 从初始 /token 请求接收的令牌。

    • token_type - 该值将是 Bearer。

    • appfabric_user_id- AppFabric 用户 ID。只有使用 authorization_code 授予类型的请求才会返回此值。

    curl --location \
"https://appfabric.<region>.amazonaws.com/oauth2/token" \
--header "Content-Type: application/json" \
--header "X-Amz-Content-Sha256: <sha256_payload>" \
--header "X-Amz-Security-Token: <security_token>" \
--header "X-Amz-Date: 20230922T172215Z" \
--header "Authorization: AWS4-HMAC-SHA256 ..." \
--data "{
    \"code\": \"mM0NyJ9.MEUCIHQQgV3ChXGs2LRwxLtpsgya3ybfPYXfX-sxTAdRF-gDAiEAxX7BYKlD9krG3J2VtprOjVXZ0FSUX9whdekqJ-oampc",
    \"app_client_id\": \"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111\",
    \"grant_type\": \"authorization_code\",
    \"redirect_uri\": \"https://localhost:8080\"
}"

    如果此操作成功，则该服务将会发送回 HTTP 200 响应。

    {
    "expires_in": 43200,
    "refresh_token": "apkaeibaerjr2example",
    "token": "apkaeibaerjr2example",
    "token_type": "Bearer", 
    "appfabric_user_id" : "<userId>"
}

第 3 步。将 AppFabric 用户门户 URL 添加到您的应用程序

最终用户需要获得授权 AppFabric 才能访问其应用程序中用于生成见解的数据。 AppFabric 通过构建专门的用户门户（弹出式屏幕）供最终用户授权其应用程序，消除了应用程序开发者拥有此流程的复杂性。当用户准备好提高工作效率时，他们将被带到用户门户，该门户使他们能够连接和管理用于生成见解和跨应用程序操作的应用程序。 AppFabric 登录后，用户可以将应用程序连接到 AppFabric 以提高工作效率，然后返回到您的应用程序以探索见解和操作。要将应用程序与集成 AppFabric 以提高工作效率，您需要在应用程序中添加特定 AppFabric 的 URL。此步骤对于使用户能够直接从您的应用程序访问 AppFabric 用户门户至关重要。

  1. 导航到应用程序的设置，找到用于添加重定向 URL 的部分。

  2. 找到相应区域后，将以下 AppFabric URL 作为重定向 URL 添加到您的应用程序：

    https://userportal.appfabric.<region>.amazonaws.com/eup_login

添加 URL 后，您的应用程序将设置为将用户定向到 AppFabric用户门户。在这里，用户可以登录并连接和管理 AppFabric 用于生成生产力见解的应用程序。

第 4 步。 AppFabric 用于显示跨应用程序的见解和操作

用户连接应用程序后，您可以利用用户的见解，通过帮助减少应用程序和上下文切换来提高他们的工作效率。 AppFabric 仅根据用户有权访问的内容为用户生成见解。 AppFabric 将用户数据存储在 AWS 账户 所有者中 AppFabric。有关如何 AppFabric 使用您的数据的信息，请参阅数据处理。

您可以使用以下 AI 驱动的 API 在应用程序内生成和显示用户级见解和操作：

  • ListActionableInsights — 有关更多信息，请参阅下面的可操作的见解部分。

  • ListMeetingInsights — 有关更多信息，请参阅本指南后面的会议准备部分。

可操作的见解 (ListActionableInsights)

ListActionableInsights API 可帮助用户根据其应用程序（包括电子邮件、日历、消息、任务等）中的活动显示可操作的见解，帮助用户更好地管理自己的一天。返回的见解还将显示指向用于生成见解的构件的嵌入式链接，从而帮助用户快速查看生成见解时使用了哪些数据。此外，API 可能会根据见解返回建议的操作，并允许用户从您的应用程序执行跨应用程序操作。具体而言，API 与 Asana、Google Workspace、Microsoft 365 和 Smartsheet 等平台集成，使用户能够发送电子邮件、创建日历事件和创建任务。大型语言模型 (LLM) 可以在建议的操作中预先填充详细信息（例如电子邮件正文或任务名称），用户可以在执行前对其进行自定义，从而简化决策并提高工作效率。与最终用户授权应用程序的体验类似， AppFabric 使用相同的专用门户供用户查看、编辑和执行跨应用程序操作。要执行操作， AppFabric 需要 ISV 将用户重定向到 AppFabric 用户门户，他们可以在其中查看操作详细信息并执行这些操作。生成的每个操作都 AppFabric 有一个唯一的 URL。此 URL 在 ListActionableInsights API 响应的响应中可用。

以下是支持的跨应用程序操作以及哪些应用程序的摘要：

  • 发送电子邮件（Google Workspace、Microsoft 365）

  • 创建日历事件（Google Workspace、Microsoft 365）

  • 创建任务（Asana、Smartsheet）

请求字段

  • nextToken（可选）- 用于获取下一组见解的分页令牌。

  • includeActionExecutionStatus - 接受操作执行状态列表的筛选条件。操作将根据传入的状态值进行筛选。可能的值：NOT_EXECUTED | EXECUTED

请求标头

  • 授权标头需要与 Bearer Token 值一起传入。

响应字段

  • insightId - 生成的见解的唯一 ID。

  • insightContent - 这将返回见解摘要以及用于生成见解的构件的嵌入式链接。注意：这将是一个包含嵌入式链接（<a> 标签）的 HTML 内容。

  • insightTitle - 生成的见解的标题。

  • createdAt - 生成的见解的时间。

  • actions - 为生成的见解建议的操作列表。操作对象:

    • actionId - 生成的操作的唯一 ID。

    • actionIconUrl - 建议在其中执行操作的应用程序的图标 URL。

    • actionTitle - 生成的操作的标题。

    • actionUrl-供最终用户在用户门户中查看和执行操作 AppFabric的唯一 URL。注意：为了执行操作，ISV 应用程序将使用此 URL 将用户重定向到 AppFabric 用户门户（弹出屏幕）。

    • actionExecutionStatus - 指示操作状态的枚举。可能的值包括：EXECUTED | NOT_EXECUTED

  • nextToken（可选）- 用于获取下一组见解的分页令牌。这是一个可选字段，如果返回 null，则表示没有更多的见解可供加载。

有关更多信息，请参阅 ActionableInsights。

curl -v --location \
  "https://productivity.appfabric.<region>.amazonaws.com"\
"/actionableInsights" \
  --header "Authorization: Bearer <token>"

如果此操作成功，则该服务将会发送回 HTTP 200 响应。

200 OK

{
    "insights": [
        {
            "insightId": "7tff3412-33b4-479a-8812-30EXAMPLE1111",
            "insightContent": "You received an email from James
            regarding providing feedback
            for upcoming performance reviews.",
            "insightTitle": "New feedback request",
            "createdAt": 2022-10-08T00:46:31.378493Z,
            "actions": [
                {
                    "actionId": "5b4f3412-33b4-479a-8812-3EXAMPLE2222",
                    "actionIconUrl": "https://d3gdwnnn63ow7w.cloudfront.net/eup/123.svg",
                    "actionTitle": "Send feedback request email",
                    "actionUrl": "https://userportal.appfabric.us-east-1.amazonaws.com/action/action_id_1"
                    "actionExecutionStatus": "NOT_EXECUTED"
                }
            ]
        },
        {
            "insightId": "2dff3412-33b4-479a-8812-30bEXAMPLE3333",
            "insightContent":"Steve sent you an email asking for details on project. Consider replying to the email.",
            "insightTitle": "New team launch discussion",
            "createdAt": 2022-10-08T00:46:31.378493Z,
            "actions": [
                {
                    "actionId": "74251e31-5962-49d2-9ca3-1EXAMPLE1111",
                    "actionIconUrl": "https://d3gdwnnn63ow7w.cloudfront.net/eup/123.svg",
                    "actionTitle": "Reply to team launch email",
                    "actionUrl": "https://userportal.appfabric.us-east-1.amazonaws.com/action/action_id_2"
                    "actionExecutionStatus": "NOT_EXECUTED"
                }
            ]
        }
    ],
    "nextToken": null
}

会议准备 (ListMeetingInsights)

ListMeetingInsights API 通过总结会议目的并显示相关的跨应用程序构件（如电子邮件、消息等），帮助用户为即将举行的会议做好最充分的准备。用户现在可以快速为会议做准备，不用浪费时间在应用程序之间切换来查找内容。

请求字段

  • nextToken（可选）- 用于获取下一组见解的分页令牌。

请求标头

  • 授权标头需要与 Bearer Token 值一起传入。

响应字段

  • insightId - 生成的见解的唯一 ID。

  • insightContent - 见解的描述，以字符串格式突出显示详细信息。例如，为什么这种见解很重要。

  • insightTitle - 生成的见解的标题。

  • createdAt - 生成的见解的时间。

  • calendarEvent - 用户应关注的重要日历事件或会议。日历事件对象：

    • startTime - 事件的开始时间。

    • endTime - 事件的结束时间。

    • eventUrl - ISV 应用程序上日历事件的 URL。

  • resources - 包含与生成的见解相关的其他资源的列表。资源对象：

    • appName - 资源所属的应用程序名称。

    • resourceTitle - 资源标题。

    • resourceType - 资源的类型。可能的值包括：EMAIL | EVENT | MESSAGE | TASK

    • resourceUrl - 应用程序中的资源 URL。

    • appIconUrl - 资源所属应用程序的图像 URL。

  • nextToken（可选）- 用于获取下一组见解的分页令牌。这是一个可选字段，如果返回 null，则表示没有更多的见解可供加载。

有关更多信息，请参阅 MeetingInsights。

curl --location \
  "https://productivity.appfabric.<region>.amazonaws.com"\
"/meetingContexts" \
  --header "Authorization: Bearer <token>"

如果此操作成功，则该服务将会发送回 HTTP 201 响应。

200 OK

{
    "insights": [
        {
            "insightId": "74251e31-5962-49d2-9ca3-15EXAMPLE4444"
            "insightContent": "Project demo meeting coming up soon. Prepare accordingly",
            "insightTitle": "Demo meeting next week",
            "createdAt": 2022-10-08T00:46:31.378493Z,
            "calendarEvent": {
                    "startTime": {
                        "timeInUTC": 2023-10-08T10:00:00.000000Z,
                        "timeZone": "UTC"
                     },
                    "endTime": {
                        "timeInUTC": 2023-10-08T11:00:00.000000Z,
                        "timeZone": "UTC"
                     },
                    "eventUrl": "http://someapp.com/events/1234",
            }
            "resources": [
                {
                    "appName": "SOME_EMAIL_APP",
                    "resourceTitle": "Email for project demo",
                    "resourceType": "EMAIL",
                    "resourceUrl": "http://someapp.com/emails/1234",
                    "appIconUrl":"https://d3gdwnnn63ow7w.cloudfront.net/eup/123.svg"
                }
            ]
        },
        {
            "insightId": "98751e31-5962-49d2-9ca3-15EXAMPLE5555"
            "insightContent": "Important code complete task is now due. Consider updating the status.",
            "insightTitle": "Code complete task is due",
            "createdAt": 2022-10-08T00:46:31.378493Z,
            "calendarEvent":{
                    "startTime": {
                        "timeInUTC": 2023-10-08T10:00:00.000000Z,
                        "timeZone": "UTC"
                     },
                    "endTime": {
                        "timeInUTC": 2023-10-08T11:00:00.000000Z,
                        "timeZone": "UTC"
                     },
                    "eventUrl": "http://someapp.com/events/1234",
            },
            "resources": [
                {
                    "appName": "SOME_TASK_APPLICATION",
                    "resourceTitle": "Code Complete task is due",
                    "resourceType": "TASK",
                    "resourceUrl": "http://someapp.com/task/1234",
                    "appIconUrl": "https://d3gdwnnn63ow7w.cloudfront.net/eup/123.svg"
                }
            ]
        }
    ],
    "nextToken": null
}

为您的见解或操作提供反馈

使用 AppFabric PutFeedback API 操作为生成的见解和操作提供反馈。您可以将此功能嵌入到您的应用程序中，以提供一种提交给定 InsightId 或的反馈评分（1 到 5，其中评分越高越好）的方法 ActionId。

请求字段

  • id - 正为其提交反馈的对象的标识符。这可以是 InsightId 或 ActionId。

  • feedbackFor - 正为其提交反馈的资源类型。可能的值：ACTIONABLE_INSIGHT | MEETING_INSIGHT | ACTION

  • feedbackRating - 反馈评分从 1 到 5。评分越高越好。

响应字段

  • 没有响应字段。

有关更多信息，请参阅 PutFeedback。

curl --request POST \
  --url "https://productivity.appfabric.<region>.amazonaws.com"\
"/feedback" \
  --header "Authorization: Bearer <token>" \
  --header "Content-Type: application/json" \
  --data '{
    "id": "1234-5678-9012",
    "feedbackFor": "ACTIONABLE_INSIGHT"
    "feedbackRating": 3
}'

如果此操作成功，则该服务会发送回带有空 HTTP 正文的 HTTP 201 响应。

第 5 步。 AppFabric 请求验证您的申请

到目前为止，您已经更新了应用程序界面以嵌入 AppFabric 跨应用程序的见解和操作，并收到了针对单个用户的见解。在您对测试感到满意并希望将 AppFabric丰富体验扩展到其他用户之后，可以将您的申请提交给以 AppFabric 供审核和验证。 AppFabric 将在实现广泛采用之前验证应用程序信息，以帮助保护应用程序开发人员、最终用户及其数据，从而为以负责任的方式扩大用户采用率铺平道路。

启动验证流程

通过发送电子邮件至 appfabric-appverification@amazon.com 并请求验证您的应用程序，来开始验证流程。

在您的电子邮件中包括以下详细信息：

  • 你的 AWS 账户 身份证

  • 您正在寻求验证的应用程序的名称

  • 你的 AppClient 身份证

  • 您的联系信息

此外，请提供以下信息（如果可用），以帮助我们评估优先级和影响：

  • 您计划授予访问权限的估计用户数

  • 您的目标发布日期

注意

如果您有 AWS 账户 经理或 AWS 合作伙伴开发经理，请将其复制到您的电子邮件中。包括这些联系人可以帮助加快验证过程。

验证标准

在启动验证过程之前，您必须满足以下标准：

  • 为了提高工作效率， AWS 账户 必须使用有效 AppFabric 的

此外，您至少满足下列条件之一：

  • 您的组织是至少 AWS Partner Network 具有 “AWS 精选” 级别的 AWS 合作伙伴。有关更多信息，请参阅 AWS 合作伙伴服务等级。

  • 在过去三年中，您的组织应该在 AppFabric 服务上花费至少10,000美元。

  • 您的应用程序应列在 AWS Marketplace上。有关更多信息，请参阅 AWS Marketplace。

等待验证状态更新

审核您的申请后，我们将通过电子邮件回复，您的申请状态 AppClient 将从变pending_verification为verified。如果您的申请被拒绝，则需要重新启动验证流程。