Desenvolver extensões para projetos públicos

Serviços do Azure DevOps

O Azure DevOps Services dá suporte a projetos públicos e privados. Projetos privados restringem o acesso a usuários autenticados com permissões explícitas. Projetos públicos permitem que usuários que não são membros visualizem o conteúdo do projeto em modo somente leitura.

Um usuário não membro pode ser:

• Anônimo: não autenticado no Azure DevOps Services
• Público: Autenticado no Azure DevOps Services, mas não membro da organização

Usuários não membros veem as mesmas exibições que os usuários autenticados, mas o Azure DevOps oculta ou desabilita funcionalidades não públicas, como configurações, ações e operações de fila de build.

Decidir se deseja tornar uma extensão visível para usuários não membros

Como desenvolvedor de extensão, você pode disponibilizar toda ou parte da extensão para usuários que não são membros. Esses usuários só podem usar sua extensão de dentro de projetos públicos. Se você optar por não disponibilizar sua extensão para usuários não membros, não precisará de alterações e a decisão não afetará os membros que usam sua extensão em projetos públicos.

Use esta lista de verificação para ajudar a decidir se você deve disponibilizar sua extensão para usuários que não são membros:

Configurar a visibilidade da contribuição

Por padrão, o Azure DevOps mostra contribuições apenas para membros da organização. Para dar visibilidade de usuários não membros a uma contribuição, defina o restrictedTo atributo nessa contribuição. O valor é uma matriz de cadeia de caracteres que lista quais tipos de usuário devem ver a contribuição. Os valores possíveis incluem:

• member: um usuário autenticado que é membro da organização
• public: um usuário autenticado que não é membro da organização
• anonymous: um usuário não autenticado

Tornar um hub visível para usuários anônimos, públicos e membros

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

Você também pode definir a visibilidade padrão de todas as contribuições em sua extensão definindo o restrictedTo atributo na raiz do manifesto da extensão. Em seguida, você pode substituir esse padrão em contribuições individuais.

Tornar todas as contribuições, exceto uma, visíveis para todos os usuários

{
    "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": {  
                ...              
            }
        }            
    ]
}

Entender as limitações para usuários que não são membros

Se você quiser disponibilizar alguns ou todos os aspectos de sua contribuição para usuários públicos, considere as seguintes limitações.

Restrições de método do SDK do VSS

O script principal do SDK, VSS.SDK.js, permite que as extensões da Web se comuniquem com o quadro pai para executar operações como inicializar a comunicação e obter informações de contexto do usuário atuais. Os seguintes métodos do SDK do VSS não dão suporte a usuários não membros:

• VSS.getAccessToken()
• VSS.getAppToken()

Limitações do serviço de dados de extensão

Como o serviço de dados de extensão gerencia dados que não estão no escopo ou protegidos para um projeto, os usuários não membros não podem ler ou gravar nenhum tipo de dados de extensão.

Lidar com erros de acesso a dados

Quando o serviço de dados não consegue acessar os dados devido a limitações de permissão impostas pelo usuário que fez a chamada, a promessa que é retornada da chamada para getValue é rejeitada. O erro passado para a função de rejeição tem uma propriedade de nome, o que ajuda você a entender por que a chamada falhou ao ler ou gravar dados.

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

Acesso à API REST

O Azure DevOps Services fornece um conjunto limitado de APIs REST para usuários não membros. Essas APIs incluem a maioria das APIs no nível da organização e do projeto para recursos que os usuários não membros geralmente podem acessar. Considere essas informações quando você decidir se deseja disponibilizar sua extensão para usuários não membros.

Recomendamos que você use a versão 5.0 e as APIs posteriores, pois o Azure DevOps disponibiliza determinadas APIs para usuários não membros apenas a partir da versão 5.0.

Referências de identidade

A maioria das APIs REST do Azure DevOps Services usa um "contrato" comum para representar um usuário ou grupo. Para proteger informações de membro, como endereços de email, o Azure DevOps omite determinados campos, como uniqueNamequando um usuário anônimo ou público invoca uma API REST.

Verificar as permissões do usuário

Use permissões para decidir se deve exibir ou habilitar uma funcionalidade em sua extensão. Use a API REST de Segurança do código de extensão da Web para verificar se o usuário atual tem permissão no Azure DevOps Services para concluir a tarefa. Essa abordagem impede que os usuários pensem que têm permissão para fazer algo, apenas para descobrir que não têm.

Verificar se o usuário tem permissão para colocar builds na fila

Este exemplo mostra como usar o cliente REST de segurança para verificar se o usuário tem permissões para enfileirar builds no projeto atual. Por padrão, os usuários não membros não têm essa permissão.

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);
  });
});

Considere os requisitos do widget do painel de controle

Assim como outros tipos de contribuições, a restrictedTo propriedade de contribuição controla a visibilidade das contribuições do widget do painel. Por exemplo, para tornar um widget visível para usuários não membros e membros:

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

Definir configurações de widget

Quando você controla a visibilidade do widget para usuários não membros, a estrutura do painel também fornece um mecanismo opcional de armazenamento em formulário aberto para as configurações de widget. Dois mecanismos indicam se as configurações de widget estão disponíveis para usuários não membros em projetos públicos.

Um widget com configurações configuráveis visíveis para usuários não membros deve seguir um dos padrões a seguir. Não seguir esses padrões impede que o widget apareça para esses usuários.

Padrão 1: O Widget declara que suas instâncias armazenam apenas configurações específicas do projeto.

Defina a propriedade da contribuição do canStoreCrossProjectSettings widget como false, indicando que as configurações do widget são específicas do projeto.

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

Padrão 2: uma instância de widget declara que suas configurações são específicas do projeto

Instâncias de widget individuais também podem indicar que suas configurações são específicas do projeto e estão disponíveis para usuários não membros. Ao salvar as configurações, o widget deve definir hasCrossProjectSettings como false na cadeia de caracteres JSON serializada:

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

Considere os requisitos de build e versão

Se a extensão contribui com uma tarefa de build ou release, você não precisa de alterações para usar essa tarefa de um pipeline em um projeto público.

Gerenciar considerações de rastreamento de item de trabalho

As extensões não funcionam para usuários não membros no contexto de um projeto público sem alterações. Isso inclui o formulário de item de trabalho, outras experiências de item de trabalho e a interação com as APIs REST de rastreamento de item de trabalho.

Limitações de formulário do item de trabalho

O Azure DevOps falha em todas as atualizações ou exclusões de item de trabalho para usuários não membros.

Tratamento de identidade

Na API REST do Azure DevOps Services versão 5.0 e posterior, o serviço retorna identidades como IdentityRef objetos em vez de cadeias de caracteres. Conforme descrito anteriormente, o Azure DevOps não retornará determinados campos, como uniqueName, nesses objetos, se um usuário não membro fizer a chamada à API.

Restrições de escopo da API

As extensões só podem invocar APIs REST com escopo de projeto quando o usuário atual não for membro da organização. O Azure DevOps rejeita todas as chamadas de API REST que não estão vinculadas a um projeto.

Limitações da consulta

Os usuários que não são membros enfrentam as seguintes limitações relacionadas às consultas de item de trabalho:

• Usuários não membros podem executar consultas conhecidas apenas por ID ou caminho
• As consultas devem estar dentro do escopo do projeto atual. O Azure DevOps exclui todos os itens de trabalho que não pertencem ao projeto atual
• Usuários não membros não podem criar novas consultas ou executar consultas WIQL

Conteúdo relacionado

• Armazenamento de dados de extensão
• Referência da API REST do Azure DevOps Services
• Visão geral de projetos públicos
• Referência de Manifesto da Extensão