Desenvolver extensões para projetos públicos

Serviços de DevOps do Azure

Os Serviços de DevOps do Azure dão suporte a projetos públicos e privados. Projetos privados restringem o acesso a usuários autenticados com permissões explícitas. Os projetos públicos permitem que usuários não-membros visualizem o conteúdo do projeto em um estado somente leitura.

Um utilizador não membro pode ser:

• Anónimo: Não autenticado nos Serviços de DevOps do Azure
• Público: autenticado nos Serviços de DevOps do Azure, mas não é membro da organização

Os usuários não membros veem os mesmos modos de exibição 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 compilação.

Decidir se uma extensão deve ser visível para usuários não membros

Como desenvolvedor de extensão, você pode disponibilizar toda ou parte da sua extensão para usuários nã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 terá impacto sobre 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 não-membros:

Configurar visibilidade de contribuição

Por padrão, o Azure DevOps mostra contribuições apenas para membros da organização. Para dar visibilidade a usuários não-membros para 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 para todas as contribuições em sua extensão definindo o restrictedTo atributo na raiz do manifesto da extensão. Em seguida, pode anular este padrão nas 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": {  
                ...              
            }
        }            
    ]
}

Compreender as limitações para utilizadores não membros

Se pretender disponibilizar alguns ou todos os aspetos da sua contribuição aos utilizadores públicos, considere as seguintes limitações.

Restrições do método VSS SDK

O script SDK principal, 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 VSS SDK não suportam 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 têm escopo ou não estão protegidos para um projeto, os usuários não-membros não podem ler ou gravar qualquer tipo de dados de extensão.

Lidar com erros de acesso a dados

Quando o serviço de dados não pode acessar dados devido a limitações de permissão pelo usuário chamador, a promessa retornada da chamada para getValue é rejeitada. O erro passado para a função rejeitar tem uma propriedade de nome, que ajuda a compreender por que motivo a chamada falhou ao tentar 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

Os Serviços de DevOps do Azure fornecem 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 no nível do projeto para recursos que os usuários não-membros geralmente podem acessar. Considere essas informações ao decidir se deseja disponibilizar sua extensão para usuários não membros.

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

Referências de identidade

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

Verifique as permissões do utilizador

Use permissões para decidir se deseja exibir ou habilitar um recurso em sua extensão. Use a API REST de segurança do código da extensão da Web para verificar se o usuário atual tem permissão nos Serviços de DevOps do Azure 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 enfileirar compilações

Este exemplo mostra como usar o cliente Security REST para verificar se o usuário tem permissões para enfileirar compilações 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 controlo

Assim como outros tipos de contribuições, a propriedade de contribuição restrictedTo 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 do widget

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

Um widget com configurações configuráveis que seja visível para usuários não-membros deve seguir um dos seguintes padrões. 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 canStoreCrossProjectSettings da contribuição do widget para false, indicando que as configurações do widget são específicas de cada 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

As instâncias individuais do widget 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 para false na cadeia de caracteres JSON em formato de string:

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

Considere os requisitos de compilação e lançamento

Se sua extensão contribuir com uma tarefa de compilação ou versão, você não precisará de alterações para usar essa tarefa de um pipeline em um projeto público.

Lidar com considerações de rastreio de itens 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 interação com APIs REST de rastreamento de item de trabalho.

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

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

Tratamento de identidade

Na API REST dos Serviços de DevOps do Azure 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 retorna determinados campos, como uniqueName, nesses objetos se um usuário não membro fizer a chamada de API.

Restrições de escopo da API

As extensões podem invocar apenas APIs REST com escopo de projeto quando o usuário atual não é um membro da organização. O Azure DevOps rejeita quaisquer chamadas de API REST sem escopo para um projeto.

Limitações de consulta

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

• Os usuários não-membros podem executar consultas conhecidas apenas por ID ou caminho
• As consultas devem ter como escopo o projeto atual. O Azure DevOps exclui todos os itens de trabalho que não pertencem ao projeto atual
• Os 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 dos Serviços de DevOps do Azure
• Visão geral dos projetos públicos
• Referência do manifesto de extensão