公共项目支持Azure DevOps Services扩展

项目
07/19/2022

Azure DevOps Services

在公共项目支持之前，Azure DevOps Services项目都是私有的。专用项目仅对有权访问该项目的用户进行身份验证，因此公众无法查看或与之交互。公共项目允许非成员用户以只读状态查看该项目的内容。

非成员用户是匿名用户 ( 向 Azure DevOps Services) 进行身份验证，或者 (对 Azure DevOps Services 进行身份验证，但不属于组织) 。

非成员用户通常看到与经过身份验证的用户相同的视图，但非公共功能是隐藏或禁用的。非公共功能（如设置和操作）的示例包括队列生成。

注意

Azure DevOps Services公共项目支持目前以受限预览版提供。如果你 vsts-public@microsoft.com 有兴趣开发支持公共项目的扩展，请联系。若要详细了解公共项目，请参阅公共Azure DevOps Services预览版。

决定是否使扩展对非成员用户可见

作为扩展开发人员，你可以将扩展的一部分或全部内容提供给非成员用户使用。这些用户只能从公共项目中使用扩展。如果选择不向非成员用户提供扩展，则无需更改，并且不会影响成员，无论成员是否从公共项目中使用扩展。

使用此清单来帮助确定是否应使扩展可供非成员用户使用：

扩展提供的数据与非成员用户相关
扩展在项目级别提供功能
你的扩展参与非成员用户访问的产品区域
扩展不会扩展或依赖非成员用户不可用的功能，例如数据服务或某些 Azure DevOps Services REST API。有关详细信息，请参阅本文中的限制部分。

贡献可见性

默认情况下，贡献仅对组织成员可见。若要使非成员用户能够查看贡献内容，请设置该 restrictedTo 贡献的属性。值是一个字符串数组，其中列出了哪些类型的用户应具有对贡献的可见性。可能的值包括：

member 经过身份验证的用户，它是组织的成员
public 经过身份验证的用户 ，不是 组织的成员
anonymous 未经身份验证的用户

示例：使中心对匿名用户、公共用户和成员用户可见

{
    "contributions": [
        {
            "id": "my-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-code-web.code-hub-group"
            ],
            "restrictedTo": [
                "member",
                "public",
                "anonymous"
            ],
            "properties": {
                ...            
            }
        }
    ]
}

还可以设置扩展清单根 restrictedTo 目录的属性，为扩展中所有贡献设置默认可见性。然后，可以覆盖单个贡献的此默认值。

示例：使所有用户都可以看到每个贡献（一个除外）

{
    "id:": "my-extension",
    "name": "My Extension",
    "version": "1.0.0",
    ...
    "restrictedTo": [
           "anonymous",
           "public",
           "member"
    ],
    "contributions": [
        {
            "id": "my-member-only-widget",
            "type": "ms.vss-dashboards-web.widget",
            "restrictedTo": [
                "member"
            ],
            "properties": {
                ...
            }
        },
        {
            "id": "my-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-code-web.code-hub-group"
            ],
            "properties": {  
                ...              
            }
        },
        {
            "id": "my-second-hub",
            "type": "ms.vss-web.hub",
            "targets": [
                "ms.vss-work-web.work-hub-group"
            ],
            "properties": {  
                ...              
            }
        }            
    ]
}

限制

若要向公共用户提供贡献的一部分或所有方面，请注意以下限制。

VSS SDK 方法

核心 SDK 脚本（VSS.SDK.js）允许 Web 扩展与父框架进行通信，以执行初始化通信和获取有关当前用户的上下文信息等操作。非成员用户不支持以下 VSS SDK 方法：

VSS.getAccessToken()
VSS.getAppToken()

扩展数据服务

由于扩展数据服务管理的数据没有范围或未保护到项目，因此非成员用户无法读取或写入任何类型的扩展数据。

示例：处理数据访问错误

如果数据服务由于调用用户的权限限制而无法访问数据服务，则拒绝从对的调用返回 getValue 的承诺。传递给 reject 函数的错误具有名称，这可以帮助你了解调用未能读取或写入数据的原因。

VSS.getService(VSS.ServiceIds.ExtensionData).then(function(dataService) {
    dataService.getValue("someKey").then(function(value) {
         // do something with the value
    }, function(error) {
       if (error.name === "AccessCheckException") {
           alert(error.message);
       }
    });
});

REST API

一组有限的Azure DevOps Services REST API 可供非成员用户使用。这些 API 包括大多数组织级和项目级 API，适用于非成员用户通常不可用的功能。在决定是否使扩展可供非成员用户使用时，请考虑此信息。

建议使用版本 5.0 及更高版本的 API，因为某些 API 仅适用于从版本 5.0 开始的非成员用户。

标识引用

大多数 REST AZURE DEVOPS SERVICES使用常见的"协定"来表示用户或组。若要保护成员信息（ uniqueName 如电子邮件地址）REST API匿名用户或公共用户调用成员信息时，将省略某些字段（如）。

检查用户权限

使用权限来决定是否在扩展中实现或启用功能。安全REST API从 Web 扩展代码获取，以检查当前用户Azure DevOps Services完成任务的权限。这样，用户就不会认为他们有权执行某些操作，只是发现他们无权执行某些操作。

示例：检查用户是否有权对生成进行排队

此示例演示如何使用安全 REST 客户端检查用户是否有权在当前项目中对生成进行排队。默认情况下，非成员用户没有此权限。

VSS.require(["VSS/Service", "VSS/security/RestClient"], function(VSS_Service, Security_RestClient) {
   var client = VSS_Service.getCollectionClient(Security_RestClient.SecurityHttpClient3);
 
   var securityToken = VSS.getWebContext().project.id;
 
   client.hasPermissionsBatch({
    evaluations: [
       {
           "securityNamespaceId": "33344D9C-FC72-4d6f-ABA5-FA317101A7E9",
           "token": securityToken,
           "permissions": 128 /* queue builds */
       }
    ],
    alwaysAllowAdministrators: true
}
).then(function(response) {
     console.log("Can user queue builds in this project? " + response.evaluations[0].value);
  });
});

与其他类型的贡献一样，仪表板小组件贡献的可见性由贡献属性 restrictedTo 控制。例如，使小组件对非成员用户和成员用户可见：

{
  "contributions": [
    {
      "id": "HelloWorldWidget",
      "type": "ms.vss-dashboards-web.widget",
      "targets": [
        "ms.vss-dashboards-web.widget-catalog"
      ],
      "restrictedTo": [
        "member",
        "public",
        "anonymous"
      ],
      "properties": {
          ...
      }
    }
  ]
}

控制非成员用户的小组件可见性时，仪表板框架还为小组件设置提供了可选的开放格式存储机制。有两种机制可用于指示小组件设置是否可供公共项目中的非成员用户使用。

具有非成员用户可见的可配置设置小组件 必须遵循 以下模式之一。否则会阻止小组件呈现给这些用户。

将小组件贡献的 canStoreCrossProjectSettings 属性设置为 false，指示小组件设置特定于项目。

{
    "id:": "HelloWorldWidget",
    "type": "ms.vss-dashboards-web.widget",
    ...
    "properties": {
        "canStoreCrossProjectSettings": false
    }
}

单个小组件实例还可以指示其设置特定于项目，可供非成员用户使用。保存设置时，小组件应在字符串hasCrossProjectSettingsfalse化 JSON 字符串中将设置为：

{
    "hasCrossProjectSettings": false,
    "hypotheticalWidgetOption": true,
    "backlogLevel": "Stories"
}

生成和发布注意事项

如果扩展参与生成或发布任务，则从公共项目中的管道使用该任务不需要任何更改。

工作项跟踪注意事项

在未更改的情况下，扩展对公共项目上下文中的非成员用户不起作用。这包括工作项窗体、其他工作项体验或与工作项跟踪 REST API 的交互。

工作项窗体

非成员用户无法更新或删除所有工作项。

标识

在 Azure DevOps Services REST API 5.0 及更高版本IdentityRef中，标识作为对象而不是字符串返回。如前所述，如果 API 调用 uniqueName 是由非成员用户进行，则这些对象中不会返回某些字段（如）。

API

当当前用户不是组织成员时，扩展只能调用项目范围的 REST API。任何REST API项目调用都被拒绝。

查询

对于与工作项查询相关的非成员用户，存在以下限制：

非成员用户可以按 ID 或路径运行已知查询
查询的范围必须为当前项目。不包括不属于当前项目的任何工作项
非成员用户无法创建新查询或执行 WIQL 查询