列出 teamsApp

  • 项目

命名空间：microsoft.graph

重要

Microsoft Graph /beta 版本下的 API 可能会发生更改。 不支持在生产应用程序中使用这些 API。 若要确定 API 是否在 v1.0 中可用，请使用 版本 选择器。

从 Microsoft Teams 应用 目录中列出应用。

这包括 Microsoft Teams 应用商店中的应用以及来自组织应用目录 (租户应用目录) 的应用。 若要仅从组织的应用目录获取应用，请在请求中指定 organization 为 distributionMethod 。

注意

通常，teamsApp 资源的 ID 由服务器生成。 它与 Teams 应用清单中指定的 ID 不同，除非其 distributionMethod 为 store。 对于其他情况，开发人员作为 Teams 应用清单的一部分提供的 ID 在 teamsApp 资源中标记为 externalId。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ✅ ✅ ❌

权限

为此 API 选择标记为最低特权的权限。 只有在应用需要它时，才使用更高的特权权限。 有关委派权限和应用程序权限的详细信息，请参阅权限类型。 要了解有关这些权限的详细信息，请参阅 权限参考。

权限类型 最低特权权限 更高特权权限
委派（工作或学校帐户） AppCatalog.Submit AppCatalog.Read.All、AppCatalog.ReadWrite.All、Directory.Read.All、Directory.ReadWrite.All
委派（个人 Microsoft 帐户） 不支持。 不支持。
应用程序 AppCatalog.Read.All AppCatalog.ReadWrite.All

注意

仅出于向后兼容性而支持 Directory.Read.All 和 Directory.ReadWrite.All 权限。 建议更新解决方案以使用备用权限，并避免今后使用这些权限。

HTTP 请求

GET /appCatalogs/teamsApps

可选的查询参数

此方法支持 $filter、 $select和 $expandOData 查询参数 ，以帮助自定义响应。

使用 $expand=AppDefinitions 返回有关应用状态的详细信息，例如 publishingState，它反映应用提交评审状态，并返回应用是已批准、拒绝还是仍在审查中。

注意： 可以筛选 teamsApp 对象的任何字段，以缩短结果列表。 可以使用以下任一筛选器操作：等于、不等于 和、或、不。

请求标头

标头 值
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。

请求正文

请勿提供此方法的请求正文。

响应

如果成功，此方法在 200 OK 响应正文中返回响应代码和 teamsApp 对象列表。

示例

示例 1：列出特定于租户的所有应用程序

以下示例列出了特定于租户的所有应用程序。

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/beta/appCatalogs/teamsApps?$filter=distributionMethod eq 'organization'

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "displayName": "Test App",
      "distributionMethod": "organization"
    }
  ]
}

示例 2：列出具有给定 ID 的应用程序

以下示例列出了具有给定 ID 的应用程序。

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/beta/appCatalogs/teamsApps?$filter=id eq 'b1c5353a-7aca-41b3-830f-27d5218fe0e5'

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "b1c5353a-7aca-41b3-830f-27d5218fe0e5",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "displayName": "Test App",
      "distributionMethod": "organization"
    }
  ]
}

示例 3：基于 Teams 应用清单 ID 查找应用程序

以下示例列出与 Teams 应用清单中指定的 ID 匹配的应用程序。 在此示例中，Teams 应用的清单 ID 为 cf1ba4c7-f94e-4d80-ba90-5594b641a8ee。

请求

以下示例显示了一个请求。

GET  https://graph.microsoft.com/beta/appCatalogs/teamsApps?$filter=externalId eq 'cf1ba4c7-f94e-4d80-ba90-5594b641a8ee'

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps",
    "value": [
        {
            "id": "22f73bbe-f67a-4dea-bd54-54cac718cb2b",
            "externalId": "cf1ba4c7-f94e-4d80-ba90-5594b641a8ee",
            "displayName": "YPA",
            "distributionMethod": "organization"
        }
    ]
  }

示例 4：列出具有给定 ID 的应用程序，并返回提交评审状态

以下示例列出具有给定 ID 的应用程序，并展开 appDefinitions 以返回 publishingState，它反映了应用的提交评审状态。 Submitted 表示评审挂起， published 表示管理员已批准应用，表示 rejected 管理员拒绝应用。

请求

以下示例显示了一个请求。

GET  https://graph.microsoft.com/beta/appCatalogs/teamsApps?$filter=id eq '876df28f-2e78-423b-94a5-44181bd0e225'&$expand=appDefinitions

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "876df28f-2e78-423b-94a5-44181bd0e225",
      "externalId": "f31b1263-ba99-435a-a679-911d24850d7c",
      "displayName": "Test App",
      "distributionMethod": "Organization",
      "appDefinitions": [
        {
          "id": "NGQyMGNiNDUtZWViYS00ZTEyLWE3YzktMGQ0NDgzYjYxNzU2IyMxLjAuMA==",
          "teamsAppId": "876df28f-2e78-423b-94a5-44181bd0e225",
          "displayName": "Test App",
          "version": "1.0.1",
          "publishingState": "published",
          "shortDescription": "Types Of Cards.",
          "description": "This sample shows the feature where user can send different types of cards using bot.",
          "lastModifiedDateTime": "2020-11-23T21:36:00.9437445Z",
          "createdBy": null 
        }
      ]
    }
  ]
}

示例 5：仅列出目录中包含机器人的应用的详细信息

以下示例仅列出目录中包含机器人的应用。

请求

以下示例显示了一个请求。

GET  https://graph.microsoft.com/beta/appCatalogs/teamsApps?$expand=appDefinitions($expand=bot)&$filter=appDefinitions/any(a:a/bot ne null)

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps(appDefinitions(bot()))",
    "value": [
        {
            "id": "8a1ed7a3-5c78-46b2-8504-f9da00a1d1a6",
            "externalId": "3CAB7543-216D-47C6-986C-6247670F4663",
            "displayName": "Ducks-3",
            "distributionMethod": "organization",
            "appDefinitions": [
                {
                    "@odata.etag": "ImNOTW1CR2V1VzgwczlEblVidU00UHc9PSI=",
                    "id": "OGExZWQ3YTMtNWM3OC00NmIyLTg1MDQtZjlkYTAwYTFkMWE2IyMxLjAuOSMjUmVqZWN0ZWQ=",
                    "teamsAppId": "8a1ed7a3-5c78-46b2-8504-f9da00a1d1a6",
                    "displayName": "Ducks-3",
                    "version": "1.0.9",                  
                    "publishingState": "rejected",
                    "shortDescription": "quaerat quasi magnam. slight change. 5",
                    "description": "Aliquid placeat animi debitis accusamus. Non perferendis ullam. Quis est consequuntur vitae provident. Sunt laudantium id aut. slight change 5",
                    "lastModifiedDateTime": "2020-11-23T21:36:00.9437445Z",
                    "createdBy": {
                        "application": null,
                        "device": null,
                        "conversation": null,
                        "user": {
                            "id": "70292a90-d2a7-432c-857e-55db6d8f5cd0",
                            "displayName": null,
                            "userIdentityType": "aadUser"
                        }
                    },
                    "bot": {
                        "id": "bb9f67a4-893b-48d7-ab17-40ed466c0f16"
                    }
                }
            ]
        },
        {
            "id": "30909dee-f7dd-4f89-8b3b-55de2e32489c",
            "externalId": "0ebd3f4d-ca91-495b-a227-a17d298e22cc",
            "displayName": "Self-Install-App-E2E-Tests",
            "distributionMethod": "organization",
            "appDefinitions": [
                {
                    "@odata.etag": "IkwzVDlMOTBSSEdTMFducHUyYkpjVmc9PSI=",
                    "id": "MzA5MDlkZWUtZjdkZC00Zjg5LThiM2ItNTVkZTJlMzI0ODljIyM2LjAuMCMjU3VibWl0dGVk",
                    "teamsAppId": "30909dee-f7dd-4f89-8b3b-55de2e32489c",                
                    "displayName": "Self-Install-App-E2E-Tests",
                    "version": "6.0.0",
                    "publishingState": "submitted",
                    "shortDescription": "A conversational smart assistant from MSX that surfaces real-time insights.",
                    "description": "For MSX Users: A conversational role-based smart assistant that will enable Enterprise sellers (AE, ATS, SSP, TSP) to be more productive by surfacing real-time insights, recommendations, actions and notifications, and by automating repetitive tasks.",
                    "lastModifiedDateTime": "2020-08-25T18:40:13.035341Z",
                    "createdBy": {
                        "application": null,
                        "device": null,
                        "conversation": null,
                        "user": {
                            "id": "c071a180-a220-43a1-adaf-e8db95c4a7d6",
                            "displayName": null,
                            "userIdentityType": "aadUser"
                        }
                    },
                    "bot": {
                        "id": "da7d471b-de7d-4152-8556-1cdf7a564f6c"
                    }
                }
            ]
        }
    ]
}

示例 6：列出按应用安装范围筛选的应用的详细信息

以下示例仅列出可在用户的个人范围内安装的应用。

请求

以下示例显示了一个请求。

GET  https://graph.microsoft.com/beta/appCatalogs/teamsApps?$expand=appDefinitions($select=id,displayName,allowedInstallationScopes)&$filter=appDefinitions/any(a:a/allowedInstallationScopes has 'personal')

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps(appDefinitions(id,displayName,allowedInstallationScopes))",
    "value": [
        {
            "id": "5a542e1c-5f8c-4793-8b0c-6082464b2378",
            "externalId": "4b3ec336-b998-4623-9e25-d4182fb82159",
            "displayName": "Carriage",
            "distributionMethod": "organization",
            "appDefinitions": [
                {
                    "id": "MWE1NDJlMWMtNWY4Yy00NzkzLThiMGMtNjA4MjQ2NGIyMzc4IyMxLjAuMCMjUHVibGlzaGVk",
                    "displayName": "Carriage",
                    "allowedInstallationScopes": "personal"
                }
            ]
        }
    ]
}

示例 7：列出具有给定 ID 的应用程序，并仅返回应用所需的特定于资源的权限

以下示例列出具有给定 ID 的应用，并返回与其关联的特定于资源的权限。

请求

以下示例显示了一个请求。

GET  https://graph.microsoft.com/beta/appCatalogs/teamsApps?$filter=id+eq+'a5228c26-a9ae-4702-90e0-79a5246d2f7d'&$expand=appDefinitions($select=id,authorization)

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps(appDefinitions(id,authorization))",
    "value": [
        {
            "id": "a5228c26-a9ae-4702-90e0-79a5246d2f7d",
            "externalId": "a55ec032-36e9-4b60-b604-34b2fe55abf1",
            "displayName": "teamsDelegatedRscTests",
            "distributionMethod": "organization",
            "appDefinitions@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps('a5228c26-a9ae-4702-90e0-79a5246d2f7d')/appDefinitions(id,authorization)",
            "appDefinitions": [
                {
                    "id": "YTUyMjhjMjYtYTlhZS00NzAyLTkwZTAtNzlhNTI0NmQyZjdkIyMxLjAuMCMjUHVibGlzaGVk",
                    "authorization": {
                        "requiredPermissionSet": {
                            "resourceSpecificPermissions": [
                                {
                                    "permissionValue": "Channel.Create.Group",
                                    "permissionType": "application"
                                },
                                {
                                    "permissionValue": "Channel.Delete.Group",
                                    "permissionType": "application"
                                },
                                {
                                    "permissionValue": "ChannelMeeting.ReadBasic.Group",
                                    "permissionType": "delegated"
                                }
                            ]
                        }
                    }
                }
            ]
        }
    ]
}

示例 8：列出应用目录中包含仪表板卡的应用的详细信息

以下示例仅列出包含仪表板 卡的应用目录中的应用。

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/beta/appCatalogs/teamsApps?$expand=appDefinitions($expand=dashboardCards)&$filter=appDefinitions/any(a:a/dashboardCards/$count+ne+0)

响应

以下示例显示了相应的响应。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps(appDefinitions(dashboardCards()))",
  "value": [
    {
      "id": "ff43cabf-9244-4260-a68e-5403ec648e96",
      "externalId": "c8d1b752-2762-4e8c-9aba-3537d339e17a",
      "displayName": "Dashboard Card App",
      "distributionMethod": "organization",
      "appDefinitions@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps('ff43cabf-9244-4260-a68e-5403ec648e96')/appDefinitions(dashboardCards())",
      "appDefinitions": [
        {
          "id": "ZmY0M2NhYmYtOTI0NC00MjYwLWE2OGUtNTQwM2VjNjQ4ZTk2IyMxLjAuMCMjUHVibGlzaGVk",
          "teamsAppId": "ff43cabf-9244-4260-a68e-5403ec648e96",
          "azureADAppId": null,
          "displayName": "Dashboard Card App",
          "version": "1.0.0",
          "requiredResourceSpecificApplicationPermissions": [],
          "publishingState": "published",
          "shortdescription": "Test app with dashboard cards",
          "description": "Test app with dashboard cards",
          "lastModifiedDateTime": null,
          "allowedInstallationScopes": "team,groupChat,personal",
          "serializedInternalDefinition": null,
          "createdBy": null,
          "authorization": {
            "requiredPermissionSet": {
              "resourceSpecificPermissions": []
            }
          },
          "dashboardCards@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps('ff43cabf-9244-4260-a68e-5403ec648e96')/appDefinitions('ZmY0M2NhYmYtOTI0NC00MjYwLWE2OGUtNTQwM2VjNjQ4ZTk2IyMxLjAuMCMjUHVibGlzaGVk')/dashboardCards",
          "dashboardCards": [
            {
              "id": "210a65de-24ce-445e-9e1e-dd4ef0f0114b",
              "displayName": "sample1",
              "description": "this is the first sample of the card",
              "pickerGroupId": "110a65de-24ce-445e-9e1e-dd4ef0f0114b",
              "defaultSize": "large",
              "icon": {
                "iconUrl": null,
                "officeUIFabricIconName": "VivaLogo"
              },
              "contentSource": {
                "sourceType": "bot",
                "botConfiguration": {
                  "botId": "19806762-da13-422d-837a-f1061bc1f572"
                }
              }
            },
            {
              "id": "210a65de-24ce-445e-9e1e-dd4ef0f0114a",
              "displayName": "sample2",
              "description": "Second sample of dashboard card.",
              "pickerGroupId": "110b65de-24ce-445e-9e1e-dd4ef0f0114b",
              "defaultSize": "medium",
              "icon": {
                "iconUrl": "https://publiccdn.contoso.com/icons/card-icon.svg",
                "officeUIFabricIconName": null
              },
              "contentSource": {
                "sourceType": "bot",
                "botConfiguration": {
                  "botId": "19806762-da13-422d-837a-f1061bc1f672"
                }
              }
            }
          ]
        }
      ]
    },
    {
      "id": "4c3aa29d-ea6b-4e68-9ae0-9e6f1251eea0",
      "externalId": "c85a15d9-b835-49f4-99d6-a5cbe89734d3",
      "displayName": "Dashboard Card Test",
      "distributionMethod": "organization",
      "appDefinitions@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps('4c3aa29d-ea6b-4e68-9ae0-9e6f1251eea0')/appDefinitions(dashboardCards())",
      "appDefinitions": [
        {
          "id": "NGMzYWEyOWQtZWE2Yi00ZTY4LTlhZTAtOWU2ZjEyNTFlZWEwIyMxLjAuMCMjUHVibGlzaGVk",
          "teamsAppId": "4c3aa29d-ea6b-4e68-9ae0-9e6f1251eea0",
          "azureADAppId": null,
          "displayName": "Dashboard Card Test",
          "version": "1.0.0",
          "requiredResourceSpecificApplicationPermissions": [],
          "publishingState": "published",
          "shortdescription": "Test app with dashboard cards",
          "description": "Test app with dashboard cards",
          "lastModifiedDateTime": null,
          "allowedInstallationScopes": "team,groupChat,personal",
          "serializedInternalDefinition": null,
          "createdBy": null,
          "authorization": {
            "requiredPermissionSet": {
              "resourceSpecificPermissions": []
            }
          },
          "dashboardCards@odata.context": "https://graph.microsoft.com/beta/$metadata#appCatalogs/teamsApps('4c3aa29d-ea6b-4e68-9ae0-9e6f1251eea0')/appDefinitions('NGMzYWEyOWQtZWE2Yi00ZTY4LTlhZTAtOWU2ZjEyNTFlZWEwIyMxLjAuMCMjUHVibGlzaGVk')/dashboardCards",
          "dashboardCards": [
            {
              "id": "210a65de-24ce-445e-9e1e-dd4ef0f0114b",
              "displayName": "sample1",
              "description": "this is the first sample of the card",
              "pickerGroupId": "110a65de-24ce-445e-9e1e-dd4ef0f0114b",
              "defaultSize": "large",
              "icon": {
                "iconUrl": null,
                "officeUIFabricIconName": "VivaLogo"
              },
              "contentSource": {
                "sourceType": "bot",
                "botConfiguration": {
                  "botId": "19806762-da13-422d-837a-f1061bc1f572"
                }
              }
            },
            {
              "id": "210a65de-24ce-445e-9e1e-dd4ef0f0114a",
              "displayName": "sample2",
              "description": "Second sample of dashboard card.",
              "pickerGroupId": "110b65de-24ce-445e-9e1e-dd4ef0f0114b",
              "defaultSize": "medium",
              "icon": {
                "iconUrl": "https://publiccdn.contoso.com/icons/card-icon.svg",
                "officeUIFabricIconName": null
              },
              "contentSource": {
                "sourceType": "bot",
                "botConfiguration": {
                  "botId": "19806762-da13-422d-837a-f1061bc1f672"
                }
              }
            }
          ]
        }
      ]
    }
  ]
}

相关内容