Использование#

Важно

Для использования Argo Workflows API получите token авторизации у системного администратора.

Запуск workflow#

Endpoint: POST https://{argo-url}/argowf/api/v1/workflows/getdocs-prod/submit, где {argo-url} - адрес Argo Workflows.

Шаблон тела запроса:

{
    "namespace": "getdocs-prod",
    "resourceKind": "WorkflowTemplate",
    "resourceName": "<workflow-template-name>",
    "submitOptions": {
        "parameters": [
            "<parameter_name1>=<parameter_value1>",
            ...,
            "<parameter_nameN>=<parameter_valueN>"
        ],
        "labels": "submit-from-api=true"
    }
}

JSON поле

Значение

Описание

namespace

getdocs-prod

Пространство имен, в котором находится шаблон workflow

resourceKind

WorkflowTemplate

Тип ресурса. Workflow будет создаваться из шаблона, поэтому должно быть указано WorkflowTemplate

resourceName

<workflow-template-name>

Имя шаблона workflow. Доступные значения:
* build-doc
* build-site
* load-to-nexus
* print-doc
* validate-doc

submitOptions.parameters

<parameter_name1>=<parameter_value1>, ..., <parameter_nameN>=<parameter_valueN>

Список параметров для запуска workflow. Список параметров для каждого workflow представлен в разделе Запуск workflow Руководства пользователя.
Если параметров нет, то данное JSON поле не нужно указывать

submitOptions.labels

submit-from-api=true

Метки для быстрого поиска workflow в общем списке.
Рекомендуется использовать submit-from-api=true для отличия данных workflow от созданных пользователями в веб-интерфейсе

Тело ответа: После отправки данного запроса сервер вернет ответ с созданным workflow. В поле metadata.name содержится имя workflow.

Тело запроса для каждого шаблона workflow#

В примерах ниже обязательные поля подсвечены.

build-doc#

{
    "namespace": "getdocs-prod",
    "resourceKind": "WorkflowTemplate",
    "resourceName": "build-doc",
    "submitOptions": {
        "parameters": [
            "repo_url=<value>",
            "repo_branch=<value>",
            "repo_commit=<value>",
            "doc_dir=<value>",
            "code=<value>",
            "version=<value>",
        ],
        "labels": "submit-from-api=true"
    }
}

build-site#

{
    "namespace": "getdocs-prod",
    "resourceKind": "WorkflowTemplate",
    "resourceName": "build-site",
    "submitOptions": {
        "labels": "submit-from-api=true"
    }
}

load-to-nexus#

{
    "namespace": "getdocs-prod",
    "resourceKind": "WorkflowTemplate",
    "resourceName": "load-to-nexus",
    "submitOptions": {
        "parameters": [
            "code=<value>",
            "version=<value>",
            "group_id=<value>",
        ],
        "labels": "submit-from-api=true"
    }
}

validate-doc#

{
    "namespace": "getdocs-prod",
    "resourceKind": "WorkflowTemplate",
    "resourceName": "validate-doc",
    "submitOptions": {
        "parameters": [
            "repo_url=<value>",
            "repo_branch=<value>",
            "repo_commit=<value>",
            "doc_dir=<value>",
            "code=<value>",
            "version=<value>",
            "validation_rules_branch=<value>"
        ],
        "labels": "submit-from-api=true"
    }
}
{
    "namespace": "getdocs-prod",
    "resourceKind": "WorkflowTemplate",
    "resourceName": "print-doc",
    "submitOptions": {
        "parameters": [
            "code=<value>",
            "version=<value>",
            "documents=<value>",
            "include_components=<value>",
            "format=<value>",
            "package=<value>"
        ],
        "labels": "submit-from-api=true"
    }
}

Получение информации о workflow#

Endpoint: GET https://{argo-url}/argowf/api/v1/workflows/getdocs-prod/{name} , где {name} - имя workflow, {argo-url} - адрес Argo Workflows.

Тело ответа: После отправки данного запроса сервер вернет ответ с полной информацией о workflow. В поле status.phase содержится текущий статус workflow:

  • в поле status.nodes.<workflow-name>.outputs.parameters содержится объект с результирующими параметрами workflow;

  • в поле status.nodes.<workflow-name>.outputs.artifacts содержится объект с результирующими артефактами workflow.

Скачивание артефакта#

Endpoint: GET https://{argo-url}/argowf/artifacts/getdocs-prod/{name}/{nodeId}/{artifactName}, где:

  • {argo-url} - адрес Argo Workflows

  • name - имя workflow;

  • nodeId - имя узла workflow. Практически во всех workflows GetDocs артефакты есть у корневого узла, его имя совпадает с именем workflow;

  • artifactName - имя артефакта. Например, в workflow build-doc имя артефакта отчета - report-draft-std-ext.

Тело ответа: После отправки данного запроса сервер вернет файл артефакта.

Примеры#

Запуск сборки документации#

В данном примере производится отправка запроса на создание workflow build-doc и ожидание его результата каждые 10 секунд.

#!/bin/bash

set -e

# Токен Argo Workflows (без 'Bearer')
if [ -z "$ARGO_TOKEN" ]; then
    echo "ERROR: ARGO_TOKEN is required."
    exit 1
fi

# Параметры workflow build-doc
if [ -z "$REPO_URL" ]; then
    echo "ERROR: REPO_URL is required."
    exit 1
fi
REPO_BRANCH=""
REPO_COMMIT=""
DOC_DIR=""
CODE=""
VERSION=""

# Базовый URL к Argo Workflows
ARGO_BASE_URL="https://{argo-url}/argowf"

# Пространство имен должно быть "getdocs-prod"
NAMESPACE="getdocs-prod"

# Запрос на создание workflow
echo "Sending request to submit build-doc workflow..."
SUBMIT_HTTP_RESPONSE=$(curl -X POST "$ARGO_BASE_URL/api/v1/workflows/$NAMESPACE/submit" \
    --write-out "HTTPSTATUS:%{http_code}" \
    -H "Authorization: Bearer $ARGO_TOKEN" \
    -H 'Content-Type: application/json' \
    -d "{
    \"namespace\": \"$NAMESPACE\",
    \"resourceKind\": \"WorkflowTemplate\",
    \"resourceName\": \"build-doc\",
    \"submitOptions\": {
        \"parameters\": [
            \"repo_url=$REPO_URL\",
            \"repo_branch=$REPO_BRANCH\",
            \"repo_commit=$REPO_COMMIT\",
            \"doc_dir=$DOC_DIR\",
            \"code=$CODE\",
            \"version=$VERSION\"
        ],
        \"labels\": \"submit-from-api=true\"
    }
}")
SUBMIT_HTTP_BODY="$(echo "$SUBMIT_HTTP_RESPONSE" | sed -E 's/HTTPSTATUS\:[0-9]{3}$//')"
SUBMIT_HTTP_STATUS=$(echo "$SUBMIT_HTTP_RESPONSE" | tr -d '\n' | sed -E 's/.*HTTPSTATUS:([0-9]{3})$/\1/')

if [ "$SUBMIT_HTTP_STATUS" != "200" ]; then
    echo "$SUBMIT_HTTP_BODY"
    exit 1
fi

WORKFLOW_NAME="$(echo "$SUBMIT_HTTP_BODY" | jq -r .metadata.name)"
WORKFLOW_URL="$ARGO_BASE_URL/workflows/$NAMESPACE/$WORKFLOW_NAME"

sleep 10

# Периодический запрос на получение результата workflow
while true; do
    echo
    echo "Sending request to check result of '$WORKFLOW_NAME'..."

    WORKFLOW_HTTP_RESPONSE=$(curl "$ARGO_BASE_URL/api/v1/workflows/$NAMESPACE/$WORKFLOW_NAME" \
        --write-out "HTTPSTATUS:%{http_code}" \
        -H "Authorization: Bearer $ARGO_TOKEN" \
        -H 'Content-Type: application/json')
    WORKFLOW_HTTP_BODY=$(echo "$WORKFLOW_HTTP_RESPONSE" | sed -E 's/HTTPSTATUS\:[0-9]{3}$//')
    WORKFLOW_HTTP_STATUS=$(echo "$WORKFLOW_HTTP_RESPONSE" | tr -d '\n' | sed -E 's/.*HTTPSTATUS:([0-9]{3})$/\1/')

    if [ "$WORKFLOW_HTTP_STATUS" != "200" ]; then
        echo "$WORKFLOW_HTTP_BODY"
        exit 1
    fi

    WORKFLOW_STATUS=$(echo "$WORKFLOW_HTTP_BODY" | jq -r .status.phase)

    if [ "$WORKFLOW_STATUS" == "null" ] || [ "$WORKFLOW_STATUS" == "Pending" ] || [ "$WORKFLOW_STATUS" == "Running" ]; then
        echo "Workflow status of '$WORKFLOW_NAME' is '$WORKFLOW_STATUS', retrying in 10 seconds..."
        sleep 10
        continue
    fi

    if [ "$WORKFLOW_STATUS" == "Failed" ] || [ "$WORKFLOW_STATUS" == "Error" ]; then
        echo "Workflow '$WORKFLOW_NAME' has failed. See logs at $WORKFLOW_URL"
        break
    fi

    if [ "$WORKFLOW_STATUS" == "Succeeded" ]; then
        echo "Workflow '$WORKFLOW_NAME' has succeeded."

        WORKFLOW_OUTPUTS=$(echo "$WORKFLOW_HTTP_BODY" | jq --arg WORKFLOW_NAME "$WORKFLOW_NAME" '.status.nodes.[$WORKFLOW_NAME].outputs')

        WORKFLOW_OUTPUTS_PARAMETERS=$(echo "$WORKFLOW_OUTPUTS" | jq '.parameters')
        echo "Workflow output parameters: $WORKFLOW_OUTPUTS_PARAMETERS"

        WORKFLOW_OUTPUTS_ARTIFACTS=$(echo "$WORKFLOW_OUTPUTS" | jq '.artifacts')
        echo "Workflow output artifacts: $WORKFLOW_OUTPUTS_ARTIFACTS"

        echo "Workflow URL: $WORKFLOW_URL"
        break
    fi

    echo "Status of workflow '$WORKFLOW_NAME' is '$WORKFLOW_STATUS', aborting."
    break
done

Запуск сборка дистрибутива#

В данном примере производится отправка запроса на создание workflow load-to-nexus и ожидание его результата каждые 10 секунд в jenkinsfile.

pipeline {
    agent {
        // Имя Jenkins агента с сетевым доступом к {argo-url}
        label '<your-agent>'
    }

    parameters {
        string(name: "CODE", description: "Код продукта")
        string(name: "VERSION", defaultValue: "", description: "Версия продукта")
        string(name: "GROUP_ID", defaultValue: "", description: "Параметр 'groupId' (если не указан, то используется 'groupId' из doc-config.ini)")
    }

    environment {
        // Базовый URL к Argo Workflows
        ARGO_BASE_URL = "https://argo-url/argowf"

        // Название Jenkins credentials типа Secret text, в котором находится строка с token (без 'Bearer')
        ARGO_CREDENTIALS = "<your-credentials>"

        // Пространство имен должно быть "getdocs-prod"
        NAMESPACE = "getdocs-prod"
    }

    stages {
        stage('Отправка запроса в GetDocs') {
            steps {
                script {
                    final String submitData = """{
                        "namespace": "$NAMESPACE",
                        "resourceKind": "WorkflowTemplate",
                        "resourceName": "load-to-nexus",
                        "submitOptions": {
                            "parameters": [
                                "code=$CODE",
                                "version=$VERSION",
                                "group_id=$GROUP_ID"
                            ],
                            "labels": "submit-from-api=true"
                        }
                    }"""

                    echo "Submitting workflow with data: $submitData"

                    withCredentials([string(credentialsId: "$ARGO_CREDENTIALS", variable: 'ARGO_TOKEN')]) {
                        // Запрос на создание workflow
                        def submitResponse = httpRequest httpMode: 'POST',
                            url: "$ARGO_BASE_URL/api/v1/workflows/$NAMESPACE/submit",
                            requestBody: submitData,
                            customHeaders: [[name: 'Authorization', value: 'Bearer ' + ARGO_TOKEN]],
                            contentType: 'APPLICATION_JSON',
                            validResponseCodes: '200',
                            ignoreSslErrors: true;

                        final Object submitResponseJson = new groovy.json.JsonSlurperClassic().parseText(submitResponse.content);
                        final String workflowName = submitResponseJson.metadata.name;

                        final String workflowUrl = "$ARGO_BASE_URL/workflows/$NAMESPACE/$workflowName"

                        sleep(10)

                        // Периодический запрос на получение результата workflow
                        while(true) {
                            def workflowResponse = httpRequest url: "$ARGO_BASE_URL/api/v1/workflows/$NAMESPACE/$workflowName",
                                customHeaders: [[name: 'Authorization', value: 'Bearer ' + ARGO_TOKEN]],
                                contentType: 'APPLICATION_JSON',
                                validResponseCodes: '200',
                                ignoreSslErrors: true;

                            final Object workflowResponseJson = new groovy.json.JsonSlurperClassic().parseText(workflowResponse.content);
                            final String workflowStatus = workflowResponseJson.status.phase;

                            if (workflowStatus in [null, "Pending", "Running"]) {
                                echo "Workflow status of '$workflowName' is '$workflowStatus', retrying in 10 seconds..."
                                sleep(10)
                                continue
                            }

                            if (workflowStatus in ["Failed", "Error"]) {
                                echo "Workflow '$workflowName' has '$workflowStatus'. See logs at $workflowUrl"
                                break
                            }

                            if (workflowStatus == "Succeeded") {
                                echo "Workflow '$workflowName' has succeeded."

                                final Object workflowOutputParameters = workflowResponseJson.status.nodes."$workflowName".outputs.parameters;

                                final String archiveLink = workflowOutputParameters.find {it.name == "link" }.value;

                                final String nonApprovedComponents = workflowOutputParameters.find {it.name == "non_approved" }.value;

                                echo "Archive link: $archiveLink"
                                echo "Non approved components: $nonApprovedComponents"
                                echo "Workflow URL: $workflowUrl"
                                break;
                            }

                            echo "Workflow status of '$workflowName' is '$workflowStatus', aborting."
                            break
                        }
                    }
                }
            }
        }
    }
}