Criar um endpoint de serviço

Azure DevOps Services | Azure DevOps Server | Azure DevOps Server 2022

Os pontos de extremidade de serviço são uma maneira de o Azure DevOps se conectar a sistemas ou serviços externos. Elas são um pacote de propriedades armazenadas com segurança pelo Azure DevOps, que inclui, mas não se limita às seguintes propriedades:

• Nome do serviço
• Descrição
• URL do servidor
• Certificados ou tokens
• Nomes de usuário e senhas

Em seguida, as extensões podem usar o ponto de extremidade do serviço para obter os detalhes armazenados e realizar as operações necessárias nesse serviço. Siga este guia para criar uma nova contribuição de ponto de extremidade de serviço e utilizá-la em sua extensão.

Visão geral da tarefa

Você pode desenvolver um ponto de extremidade de serviço criando uma extensão de exemplo para o Azure DevOps que inclui os seguintes itens:

• Um endpoint de serviço personalizado com fontes de dados, que permite que uma tarefa de build ou um widget de painel chame um endpoint REST no serviço/servidor definido pelo endpoint.
• Uma tarefa de compilação, que define duas propriedades: o terminal de serviço e uma lista de seleção, com valores preenchidos a partir da fonte de dados do terminal REST.

As etapas envolvidas na conclusão desta tarefa são:

• 1. Criar o arquivo de manifesto da extensão
• 2. Crie o pipeline de tarefas de build no arquivo task.json

Crie o arquivo de manifesto: vss-extension.json

O arquivo de manifesto define o ponto de extremidade personalizado e vincula ao manifesto task.json para a tarefa de build.

Neste artigo, a criação do arquivo de manifesto é separada nas três partes a seguir:

• Criar um ponto de extremidade de serviço
  • Visão geral da tarefa
  • Crie o arquivo de manifesto: vss-extension.json
    • Criar arquivo de manifesto básico
    • Adicionar a contribuição de ponto de extremidade personalizada
    • Adicionar a contribuição da tarefa de compilação
  • Criar a tarefa de build
    • componentestask.json
  • Autenticação
  • Próximas Etapas 
  • Conteúdo relacionado

Criar arquivo de manifesto básico

Crie um arquivo json (vss-extension.jsonpor exemplo) no home diretório da extensão.

{
"manifestVersion": 1,
  "id": "service-endpoint-tutorial",
  "version": "0.1.1",
  "name": "Sample extension that leverages a service endpoint",
  "description": "A sample Azure DevOps extension which shows how to create a custom endpoint and dynamic build task parameters taking value from a REST API.",
  "publisher": "francistotten",
  "targets": [
    {
      "id": "Microsoft.VisualStudio.Services"
    }
  ],  
  "files": [
    {
      "path": "BuildTaskFolder"
    }
  ]
}

Adicionar a contribuição de ponto de extremidade personalizada

Adicione a seguinte contributions matriz abaixo da targets matriz do conteúdo básico do manifesto.

  "contributions": [
    {
      "id": "service-endpoint",
      "description": "Service endpoint type for Fabrikam connections",
      "type": "ms.vss-endpoint.service-endpoint-type",
      "targets": [ "ms.vss-endpoint.endpoint-types" ],
      "properties": {
        "name": "fabrikam",
        "displayName": "Fabrikam server connection",
        "url": {
          "displayName": "Server Url",
          "helpText": "Url for the Fabrikam server to connect to."
        },
        "dataSources": [
          {
            "name": "Fabrikam Projects",
            "endpointUrl": "{{endpoint.url}}api/projects/index",
            "resultSelector": "jsonpath:$[*].nm"
          }

        ],
        "authenticationSchemes": [
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-token"
          },
          {
            "type": "ms.vss-endpoint.endpoint-auth-scheme-basic",
            "inputDescriptors": [
              {
                "id": "username",
                "name": "Username",
                "description": "Username",
                "inputMode": "textbox",
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              },
              {
                "id": "password",
                "name": "Password",
                "description": "Password",
                "inputMode": "passwordbox",
                "isConfidential": true,
                "validation": {
                  "isRequired": false,
                  "dataType": "string"
                }
              }
            ]
          }

        ],
        "helpMarkDown": "<a href=\"url-to-documentation\" target=\"_blank\"><b>Learn More</b></a>"
      }
    },
  ],

Se você adicionou com êxito a contribuição de serviço, verá o ponto de extremidade da Fabrikam ao tentar adicionar um novo ponto de extremidade de serviço à sua organização.

Crie um endpoint de serviço usando o endpoint Fabrikam.

Adicionar a contribuição da tarefa de build

Dentro da contributions matriz da etapa anterior, adicione o objeto a seguir ao final.

{
      "id": "build-task",
      "description": "Task with a dynamic property getting data from an endpoint REST data source",
      "type": "ms.vss-distributed-task.task",
      "targets": [ "ms.vss-distributed-task.tasks" ],
      "properties": {
        "name": "BuildTaskFolder"
      }
    }

A URL do ponto de extremidade dataSource é derivada da URL do ponto de extremidade ou de uma URL fixa, além de alguns outros valores. Para este tutorial, essa chamada REST não retorna nada e deve ser substituída por todas as chamadas REST que você deseja fazer ao seu serviço.

É possível usar outros parâmetros que não a URL do ponto de extremidade para a URL REST, por exemplo, algumas propriedades de ponto de extremidade. Por exemplo, supondo que tivéssemos uma propriedade no ponto de extremidade chamado subscriptionId, a URL REST poderia usá-la com a seguinte sintaxe: $(endpoint.subscription).

Criar a tarefa de compilação

O task.json arquivo descreve sua tarefa de build.

Crie um task.json arquivo em seu BuildTaskFolder diretório, se você ainda não criou essa pasta, faça isso agora.

{
  "id": "6557a6d2-4caf-4247-99ea-5131286a8753",
  "name": "build-task",
  "friendlyName": "Build Task that uses the service endpoint",
  "description": "Task with a dynamic property getting data from an endpoint REST data source",
  "author": "francistotten",
  "helpMarkDown": "Replace with Markdown to show in help",
  "category": "Build",
  "visibility": [
    "Build",
    "Release"
  ],
  "demands": [],
  "version": {
    "Major": "0",
    "Minor": "1",
    "Patch": "1"
  },
  "minimumAgentVersion": "1.95.0",
  "instanceNameFormat": "Service Endpoint Build Task $(project)",
  "inputs": [
    {
      "name": "FabrikamService",
      "type": "connectedService:Fabrikam",
      "label": "Fabrikam service/server end point",
      "defaultValue": "",
      "required": true,
      "helpMarkDown": "Select the Fabrikam end point to use. If needed, select 'manage', and add a new service endpoint of type 'Fabrikam server connection'"
    },
    {
      "name": "project",
      "type": "pickList",
      "label": "Fabrikam Project",
      "required": true,
      "helpMarkDown": "Select the name of the Fabrikam Project to analyze.",
      "properties": {
        "EditableOptions": "True"
      }
    }
  ],
  "dataSourceBindings": [
    {
      "target": "project",
      "endpointId": "$(FabrikamService)",
      "dataSourceName": "Fabrikam Projects"
    }
  ],
  "execution": {
    "Node": {
      "target": "sample.js",
      "argumentFormat": ""
    },
    "PowerShell3": {
      "target": "sample.ps1"
    }
  }
}

Componentes task.json

O FabrikamService objeto de entrada

Esse campo é o primeiro do tipo connectedService:Fabrikam.connectedService expressa que ele é um tipo de ponto de extremidade e que Fabrikam é o nome do objeto.

O project objeto de entrada

Este campo é o segundo. É uma lista de seleção.

• Esse campo é preenchido por uma chamada REST.
• Os valores do campo "projeto" são retirados da fonte de dados REST "Projetos" do ponto de extremidade personalizado.
• Expresso na matriz dataSourceBindings.
  • O destino é o nome do campo da tarefa de build a ser preenchido ("projeto").
  • O endpointId é o nome do campo de tarefa de build que contém o tipo de endpoint personalizado.
  • A chamada REST é escolhida pelo dataSourceName.

Se você adicionou a Tarefa Build com êxito, agora deverá ver a Tarefa Build quando estiver adicionando tarefas a um pipeline de build.

Depois de adicionar a tarefa de build ao pipeline, confirme se ela pode acessar o ponto de extremidade da Fabrikam que você criou. A lista suspensa de projetos neste tutorial está em branco, pois não estamos usando um serviço real. Depois de substituir a Fabrikam pelo seu próprio serviço, substitua a chamada de Projetos por sua própria chamada à API REST para usar dados dinâmicos dentro da sua tarefa de compilação.

Autenticação

O esquema de autenticação em um ponto de extremidade de serviço determina as credenciais que seriam usadas para se conectar ao serviço externo. Para obter mais informações e ver os seguintes esquemas de autenticação, consulte a documentação dos esquemas de autenticação.

• autenticação Básica
• Autenticação baseada em token
• Autenticação baseada em certificado
• Sem autenticação

Próximas etapas

Conteúdo relacionado

• Testar e depurar extensões
• Desenvolver uma extensão da Web
• Adicionar um decorador de pipeline