Sdílet prostřednictvím


Vytvoření serveru stavu žádosti o přijetí změn pomocí Node.js

Azure DevOps Services | Azure DevOps Server 2022 – Azure DevOps Server 2019

Pracovní postup žádosti o přijetí změn poskytuje vývojářům příležitost získat zpětnou vazbu ke svému kódu od partnerských partnerů i z automatizovaných nástrojů. Nástroje a služby třetích stran se můžou účastnit pracovního postupu žádosti o přijetí změn pomocí rozhraní API stavu žádosti o přijetí změn. Tento článek vás provede procesem vytvoření stavového serveru pro ověření žádostí o přijetí změn v úložišti Git služby Azure DevOps Services. Další informace o stavu žádosti o přijetí změn najdete v tématu Přizpůsobení a rozšíření pracovních postupů žádostí o přijetí změn se stavem žádosti o přijetí změn.

Požadavky

  • Organizace v Azure DevOps s úložištěm Git. Pokud nemáte organizaci, zaregistrujte se a nahrajte a sdílejte kód v bezplatných neomezených privátních úložištích Git.
  • Nainstalujte VS Code nebo jiný editor kódu podle vašeho výběru. Pokyny v této příručce používají VS Code, ale postup v jiných editorech kódu je podobný.

Instalace Node.js

Pokud chcete nainstalovat Node.js, stáhněte si verzi LTS, která je vhodná pro vaši platformu. Stažení obsahuje instalační program, který můžete spustit pro instalaci modulu Node.js runtime na místním počítači. Při instalaci Node.js nezapomeňte zachovat část instalace správce balíčků npm, která je ve výchozím nastavení vybraná.

Vytvoření základního webového serveru pomocí Expressu

Kroky v této části používají Express, což je zjednodušená webová architektura pro Node.js, která poskytuje řadu metod nástroje HTTP, které zjednodušují vytváření webového serveru. Tato architektura poskytuje základní funkce potřebné k naslouchání událostem žádosti o přijetí změn.

  1. Z příkazového řádku vytvořte novou složku projektu pro webový server.

    mkdir pr-server
    cd pr-server
    
  2. npm init Pomocí příkazu vytvořte nový package.json soubor pro projekt.

    npm init
    

    Stisknutím klávesy Enter přijměte výchozí hodnoty pro všechny možnosti kromě vstupního bodu. Změňte ji na hodnotu app.js

    entry point: (index.js) app.js
    
  3. Pomocí následujícího příkazu nainstalujte Express do adresáře serveru pr-server. Tím se nainstaluje Express a uloží se do seznamu závislostí.

    npm install express
    
  4. Vytvořte jednoduchou aplikaci Express, která bude stavět na serveru stavu žádosti o přijetí změn. Následující kroky jsou založené na příkladu Express Hello World. Ve VS Code otevřete složku projektu spuštěním následujícího příkazu ze pr-server složky.

    code .
    
  5. Vytvořte nový soubor (Ctrl + N) a vložte následující ukázkový kód.

    const express = require('express')
    const app = express()
    
    app.get('/', function (req, res) {
    res.send('Hello World!')
    })
    
    app.listen(3000, function () {
    console.log('Example app listening on port 3000!')
    })
    
  6. Uložte soubor jako app.js.

  7. Spusťte základní webový server pomocí následujícího příkazu:

    node app.js
    

    Ověřte, že server běží, a to tak, že přejdete na http://localhost:3000/.

Naslouchání požadavkům HTTP POST

Webový server bude přijímat POST požadavky z Azure DevOps Services, takže tyto požadavky musíte zpracovávat na serveru.

  1. Na konec app.js souboru přidejte následující kód a soubor uložte.

    app.post('/', function (req, res) {
        res.send('Received the POST')
    })
    
  2. Znovu spusťte webový server pomocí následujícího příkazu:

    node app.js
    

Konfigurace připojení služby pro události žádosti o přijetí změn

Háky služeb jsou funkce Azure DevOps Services, která může upozornit externí služby, když dojde k určitým událostem. Pro tuto ukázku budete chtít nastavit dva háky služby pro události žádosti o přijetí změn, aby bylo možné informovat stavový server. První bude pro událost vytvoření žádosti o přijetí změn a druhá bude pro aktualizovanou událost žádosti o přijetí změn.

Abyste mohli dostávat oznámení o háku služby, budete muset zpřístupnit port veřejnému internetu. Nástroj ngrok je velmi užitečný pro to v vývojovém prostředí.

  1. Stáhněte a rozbalte příslušnou verzi nástroje ngrok pro vaši platformu.

  2. Pomocí nástroje ngrok začněte naslouchat na stejném portu jako ukázkový server – port 3000. V novém příkazovém okně spusťte následující příkaz.

    ngrok http 3000
    

    Ngrok vytvoří veřejnou adresu URL, která se předá .localhost:3000 Všimněte si, že adresa URL, jak ji budete potřebovat v dalším kroku. Bude vypadat přibližně takto:

    http://c3c1bffa.ngrok.io
    
  3. Přejděte ke svému projektu v Azure DevOps, např. https://dev.azure.com/<your account>/<your project name>

  4. V navigační nabídce najeďte myší na ozubené kolo a vyberte Připojit služby.

    V nabídce správce zvolte háky služby.

  5. Pokud se jedná o váš první háček služby, vyberte + Vytvořit předplatné.

    Na panelu nástrojů vyberte Vytvořit nové předplatné.

    Pokud už máte nakonfigurované další háky služeb, vyberte zelené plus (+) a vytvořte nové předplatné háku služby.

    Výběrem zeleného plus vytvořte nové předplatné háku služby.

  6. V dialogovém okně Nový odběr hooků služeb vyberte v seznamu služeb webhooky a pak vyberte Další.

    Výběr webových háků ze seznamu služeb

  7. V seznamu triggerů událostí vyberte Žádost o přijetí změn a pak vyberte Další.

    Výběr žádosti o přijetí změn vytvořené ze seznamu triggerů událostí

  8. Na stránce Akce zadejte adresu URL z nástroje ngrok do pole adresa URL . Výběrem možnosti Test odešlete testovací událost na server.

    Zadejte adresu URL a výběrem možnosti Test otestujte připojení služby.

    V okně konzoly ngrok uvidíte příchozí POST zprávu, která vrátila 200 OKzprávu označující, že váš server přijal událost háku služby.

    HTTP Requests
    -------------
    
    POST /                         200 OK
    

    V okně Testovací oznámení vyberte kartu Odpověď a zobrazte podrobnosti odpovědi ze serveru. Měla by se zobrazit délka obsahu 17, která odpovídá délce řetězce z obslužné rutiny POST (tj. "Received the POST").

    Výběrem karty odpovědi zobrazíte výsledky testu.

  9. Zavřete okno Testovací oznámení a výběrem možnosti Dokončit vytvořte volání služby.

Znovu si projděte kroky 3 až 9, ale tentokrát nakonfigurujte aktualizovanou událost žádosti o přijetí změn.

Důležité

Nezapomeňte projít předchozí kroky dvakrát a vytvořit volání služby pro události vytvořené žádostí o přijetí změn i aktualizované události žádosti o přijetí změn.

Publikování stavu do žádostí o přijetí změn

Teď, když váš server může přijímat události háku služby při vytváření nových žádostí o přijetí změn, aktualizujte ho tak, aby odeslal stav žádosti o přijetí změn zpět.

  1. Žádosti o volání služby zahrnují datovou část JSON popisující událost. Pokud chcete pomoct parsovat JSON vrácený voláním služby, nainstalujte balíček body-parser .

    npm install body-parser
    
  2. Aktualizujte app.js , aby se při analýze application/jsonpoužíval body-parser .

    var bodyParser = require('body-parser')
    
    app.use(bodyParser.json())
    
  3. Pokud chcete zjednodušit volání rozhraní REST API do Azure Repos, nainstalujte balíček azure-devops-node-api .

    npm install azure-devops-node-api 
    
  4. Aktualizujte app.js na použití balíčku azure-devops-node-api, nastavte podrobnosti o připojení k vašemu účtu a získejte instanci rozhraní Git API.

    const vsts = require("azure-devops-node-api")
    
    const collectionURL = process.env.COLLECTIONURL    
    const token = process.env.TOKEN
    
    var authHandler = vsts.getPersonalAccessTokenHandler(token)
    var connection = new vsts.WebApi(collectionURL, authHandler)
    
    var vstsGit = connection.getGitApi().then( 
        vstsGit => {                                    
            vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
                console.log(result);
            },
            error => {
                console.log(error);
            })
        }, 
        error => { 
            console.log(error);
        } 
    );
    
  5. Vytvořte proměnnou prostředí pro adresu URL kolekce a nahraďte <your account> ji názvem vaší organizace Azure DevOps.

    setx COLLECTIONURL "https://dev.azure.com/<your account>"
    
  6. Vytvořte osobní ověřovací token (PAT), který bude aplikace používat, a to podle těchto pokynů: Ověřování pomocí tokenů pat. Měli byste vytvořit novou pat pro každou službu, kterou používáte pro přístup ke svému účtu, a odpovídajícím způsobem ji pojmete.

  7. Vytvořte pro pat proměnnou prostředí.

    setx TOKEN "yourtokengoeshere"
    
  8. Aktualizujte funkci tak post() , aby četla podrobnosti o žádosti o přijetí změn z datové části háku služby. Tyto hodnoty budete potřebovat, abyste mohli publikovat stav zpět.

    var repoId = req.body.resource.repository.id
    var pullRequestId = req.body.resource.pullRequestId
    var title = req.body.resource.title
    
  9. Sestavte stavový objekt, který se má publikovat v žádosti o přijetí změn.

    State je výčet typu GitStatusState. Slouží succeeded k označení, že žádost o přijetí změn prošla kontrolou stavu a je připravená ke sloučení.

    Jedná se description o řetězcovou hodnotu, která se uživateli zobrazí v části Stav a informační kanál o aktivitách v zobrazení podrobností žádosti o přijetí změn.

    Jedná se targetUrl o adresu URL, která se použije k vytvoření odkazu pro text popisu v části Stav a informační kanál o aktivitách. Tady můžou uživatelé získat další informace o stavu, například sestavu sestavení nebo testovací běh. Pokud není zadaná žádná adresa URL, popis se zobrazí jako text bez odkazu.

    name Kontext a genre slouží k kategorizaci stavu a odliší ho od ostatních příspěvků služeb.

        var prStatus = {
            "state": "succeeded",
            "description": "Ready for review",
            "targetUrl": "https://visualstudio.microsoft.com",
            "context": {
                "name": "wip-checker",
                "genre": "continuous-integration"
            }
        }
    
  10. Místo pouhého nevidomého publikování succeeded stavu zkontrolujte název žádosti o přijetí změn a zjistěte, jestli uživatel indikoval, jestli žádost o přijetí změn probíhá, přidáním WIP do názvu. Pokud ano, změňte stav publikovaný zpět do žádosti o přijetí změn.

        if (title.includes("WIP")) {
            prStatus.state = "pending"
            prStatus.description = "Work in progress"
        }
    
  11. Nakonec pomocí metody publikujte stav createPullRequestStatus() . Vyžaduje objekt stavu, ID úložiště a ID žádosti o přijetí změn. Vypíše odpověď do konzoly uzlu, abyste viděli výsledek příspěvku.

    vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
        console.log(result)
    })
    
  12. Výsledná metoda by měla vypadat přibližně takto:

    app.post("/", function (req, res) {
    
        // Get the details about the PR from the service hook payload
        var repoId = req.body.resource.repository.id
        var pullRequestId = req.body.resource.pullRequestId
        var title = req.body.resource.title
    
        // Build the status object that we want to post.
        // Assume that the PR is ready for review...
        var prStatus = {
            "state": "succeeded",
            "description": "Ready for review",
            "targetUrl": "https://visualstudio.microsoft.com",
            "context": {
                "name": "wip-checker",
                "genre": "continuous-integration"
            }
        }
    
        // Check the title to see if there is "WIP" in the title.
        if (title.includes("WIP")) {
    
            // If so, change the status to pending and change the description.
            prStatus.state = "pending"
            prStatus.description = "Work in progress"
        }
    
        // Post the status to the PR
        vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
            console.log(result)
        })
    
        res.send("Received the POST")
    })
    
  13. Uložte app.js a restartujte aplikaci node.

    node app.js
    

Vytvoření nové žádosti o přijetí změn pro otestování stavového serveru

Teď, když je váš server spuštěný a naslouchá oznámením o připojení služby, vytvořte žádost o přijetí změn, která ji otestuje.

  1. Začněte v zobrazení souborů. Upravte readme.md soubor v úložišti (nebo jakýkoli jiný soubor, pokud nemáte readme.md).

    V místní nabídce vyberte Upravit.

  2. Proveďte úpravy a potvrďte změny v úložišti.

    Upravte soubor a na panelu nástrojů vyberte Potvrdit.

  3. Nezapomeňte potvrdit změny do nové větve, abyste mohli vytvořit žádost o přijetí změn v dalším kroku.

    Zadejte název nové větve a vyberte Potvrdit.

  4. Vyberte odkaz Vytvořit žádost o přijetí změn.

    Na panelu návrhů vyberte Vytvořit žádost o přijetí změn.

  5. Přidejte do názvu WIP a otestujte funkčnost aplikace. Výběrem možnosti Vytvořit vytvořte žádost o přijetí změn.

    Přidání WIP do výchozího názvu žádosti o přijetí změn

  6. Po vytvoření žádosti o přijetí změn se zobrazí oddíl stavu s položkou Probíhá práce, která odkazuje na adresu URL zadanou v datové části.

    Oddíl Stav s položkou Probíhá práce

  7. Aktualizujte název žádosti o přijetí změn a odeberte text WIP a všimněte si, že se stav probíhající práce změní na Připraveno ke kontrole.

Další kroky

  • V tomto článku jste se naučili základy vytvoření služby, která naslouchá událostem žádosti o přijetí změn prostřednictvím volání služeb a může publikovat stavové zprávy pomocí rozhraní API stavu. Další informace o rozhraní API pro stav žádosti o přijetí změn najdete v dokumentaci k rozhraní REST API.
  • Nakonfigurujte zásady větve pro externí službu.