Поддержка общедоступных проектов с помощью расширений Azure DevOps Services

Статья
07/20/2023

Azure DevOps Services

До поддержки общедоступных проектов все Azure DevOps Services проекты были частными. Частные проекты прошли проверку подлинности только у пользователей, имеющих доступ к проекту, поэтому пользователи не могли видеть его или взаимодействовать с ним. Открытый проект позволяет пользователям, не являющихся участниками, просматривать содержимое этого проекта в состоянии только для чтения.

Пользователь, не являющийся участником, является либо анонимным (не прошел проверку подлинности в Azure DevOps Services), либо общедоступным (проходят проверку подлинности для Azure DevOps Services, но не принадлежат организации).

Пользователи, не являющиеся членами, обычно видят те же представления, что и пользователи, прошедшие проверку подлинности, однако недоступная функция скрыта или отключена. Примером недоступных функций, таких как параметры и действия, является сборка очереди.

Примечание

Azure DevOps Services поддержка общедоступных проектов в настоящее время доступна в режиме ограниченной предварительной версии. Обратитесь vsts-public@microsoft.com , если вы заинтересованы в разработке расширений, поддерживающих общедоступные проекты. Дополнительные сведения об общедоступных проектах см. в статье Azure DevOps Services Public Projects Limited Preview.

Решите, следует ли сделать расширение видимым для пользователей, не являющихся членами

Как разработчик расширения вы можете сделать все или часть расширения доступной для пользователей, не являющихся участниками. Эти пользователи могут использовать расширение только из общедоступного проекта. Если вы решили не делать расширение доступным для пользователей, не являющихся участниками, никаких изменений не требуется, и это не повлияет на участников, использующих ваше расширение из общедоступного проекта.

Используйте этот контрольный список, чтобы решить, следует ли сделать расширение доступным для пользователей, не являющихся участниками:

Данные, представленные расширением, относятся к пользователям, не являющихся участниками
Расширение предоставляет возможности на уровне проекта.
Расширение влияет на области продукта, доступные пользователям, не являющихся участниками
Расширение не расширяет возможности, недоступные для пользователей, не являющихся участниками, например служба данных или некоторые 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": {  
                ...              
            }
        }            
    ]
}

Ограничения

Если вы хотите сделать некоторые или все аспекты своего вклада доступными для общедоступных пользователей, имейте в виду следующие ограничения.

Методы пакета SDK VSS

Основной скрипт пакета SDK, VSS.SDK.js, позволяет веб-расширениям взаимодействовать с родительским кадром для выполнения таких операций, как инициализация связи и получение контекстных сведений о текущем пользователе. Следующие методы пакета SDK VSS не поддерживаются для пользователей, не являющихся членами:

VSS.getAccessToken()
VSS.getAppToken()

Служба данных расширения

Так как данные, управляемые службой данных расширений , не защищены в проекте, пользователи, не являющиеся участниками, не могут считывать или записывать данные расширения любого типа.

Пример: обработка ошибок доступа к данным

Если служба данных не может получить доступ к службе данных из-за ограничений разрешений вызывающего пользователя, обещание, возвращенное из вызова getValue , отклоняется. Ошибка, передаваемая в функцию отклонения, имеет имя, которое поможет вам понять, почему вызову не удалось прочитать или записать данные.

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 уровня организации и проекта для функций, недоступных пользователям, не являющихся членами, в целом. Учитывайте эти сведения при принятии решения о том, следует ли сделать расширение доступным для пользователей, не являющихся участниками.

Мы рекомендуем использовать API версии 5.0 и более поздних версий, так как некоторые API доступны только пользователям без членов, начиная с версии 5.0.

Ссылки на удостоверения

Большинство Azure DevOps Services REST API используют общий "контракт" для представления пользователя или группы. Для защиты сведений об участниках, таких как адреса электронной почты, при вызове REST API анонимным или общедоступным пользователем некоторые поля, например uniqueName , опущены.

Проверка разрешений пользователя

Используйте разрешения, чтобы решить, следует ли отображать или включать возможность в расширении. REST API безопасности используется из кода веб-расширения для проверка, имеет ли текущий пользователь разрешение на 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 свойства contribution. Например, чтобы сделать мини-приложение видимым для пользователей, не являющихся членами, и пользователями-участниками:

{
  "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"
}

Поддержка общедоступных проектов с помощью расширений Azure DevOps Services

Решите, следует ли сделать расширение видимым для пользователей, не являющихся членами

Видимость вкладов

Пример: сделать концентратор видимым для анонимных, общедоступных пользователей и пользователей-участников

Пример: сделать все вклады, кроме одного, видимыми для всех пользователей

Ограничения

Методы пакета SDK VSS

Служба данных расширения

Пример: обработка ошибок доступа к данным

Интерфейсы REST API

Ссылки на удостоверения

Проверка разрешений пользователя

Пример: проверка, есть ли у пользователя разрешение на создание очередей

Рекомендации по мини-приложениям панели мониторинга

Параметры мини-приложения

Шаблон 1. Мини-приложение объявляет свои экземпляры только для хранения параметров проекта

Шаблон 2. Экземпляр мини-приложения объявляет, что его параметры зависят от проекта

Рекомендации по сборке и выпуску

Рекомендации по отслеживанию рабочих элементов

Форма рабочего элемента

Identities

Программные интерфейсы

Запросы

Обратная связь

Обратная связь

Дополнительные ресурсы