Использование#
Важно
Для использования 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 поле |
Значение |
Описание |
|---|---|---|
|
|
Пространство имен, в котором находится шаблон workflow |
|
|
Тип ресурса. Workflow будет создаваться из шаблона, поэтому должно быть указано |
|
|
Имя шаблона workflow. Доступные значения: |
|
|
Список параметров для запуска workflow. Список параметров для каждого workflow представлен в разделе Запуск workflow Руководства пользователя. |
|
|
Метки для быстрого поиска 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"
}
}
print-doc#
{
"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 Workflowsname- имя workflow;nodeId- имя узла workflow. Практически во всех workflows GetDocs артефакты есть у корневого узла, его имя совпадает с именем workflow;artifactName- имя артефакта. Например, в workflowbuild-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
}
}
}
}
}
}
}