Клиенты API#

Для взаимодействия с контроллером по API можно использовать следующие типы клиентов:

браузер;
утилиту curl;
специальные приложения, часто называемые REST API clients;
расширения для браузера (например, Postman);
программу на любом языке программирования (например, Python).

Браузер#

Примечание

Доступ к API с помощью браузера возможен только после прохождения авторизации в графическом интерфейсе контроллера.

В адресной строке браузера введите https://<address>/api/v2/, где <address> – FQDN или IP-адрес контроллера. При выборе любой точки доступа API (API endpoint) отображается страница с результатом GET-запроcа к ней. Например, по адресу https://<address>/api/v2/ вы увидите результат запроса на получение списка всех доступных точек доступа. А по адресу https://<address>/api/v2/ping/ вы увидите результат выполнения команды GET /api/v2/ping/, которая используется для проверки доступности сервера через API.

Утилита curl#

Чтобы улучшить формат вывода JSON, в дополнение к утилите curl установите утилиту jq, с помощью команды:

sudo apt install jq

Для составления curl-запроса используйте шаблон:

curl -X GET --user <username>:<password> https://<address>/api/v2/<api_endpoint> -k -s | jq .

Здесь:

-X GET – метод HTTP, который вы хотите использовать в своем запросе. GET используется для запроса данных с сервера.
--user <username>:<password> – ключ, в котором необходимо указать имя пользователя и пароль для аутентификации на сервере.
https://<address>/api/v2/<api_endpoint> – URI, на который отправляется запрос.
<address> – FQDN или IP-адрес контроллера.
<api_endpoint> – точка доступа API (URI), к которой делается запрос.
-k или --insecure – флаг, позволяющий утилите curl игнорировать проверки сертификата SSL. Это может быть полезно для тестов или в случаях, когда используются самоподписанные сертификаты.
-s или --silent – флаг, отключающий индикаторы прогресса и сообщения об ошибках.
jq – утилита для фильтрации и преобразования данных JSON.

Примеры использования curl#

Обращение к корневой точке доступа API:

curl -X GET -k https://<address>/api/ | jq .

Пример вывода команды:

{
   "description": "AWX REST API",
   "current_version": "/api/v2/",
   "available_versions": {
      "v2": "/api/v2/"
   },
   "oauth2": "/api/o/",
   "custom_logo": "",
   "custom_login_info": "",
   "login_redirect_override": ""
}

Получение списка всех точек доступа:

curl -X GET -k https://<address>/api/v2/ | jq .

Получение списка шаблонов заданий:

curl -X GET --user <admin>:<password> -k https://<address>/api/v2/job_templates/ | jq .

Пример вывода команды:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 7,
      "type": "job_template",
      "url": "/api/v2/job_templates/7/",
      "related": {
        "created_by": "/api/v2/users/1/",
        "modified_by": "/api/v2/users/1/",
        "labels": "/api/v2/job_templates/7/labels/",
        "inventory": "/api/v2/inventories/1/",
        "project": "/api/v2/projects/6/",
        "organization": "/api/v2/organizations/1/",
        "credentials": "/api/v2/job_templates/7/credentials/",
        "last_job": "/api/v2/jobs/18/",
        "jobs": "/api/v2/job_templates/7/jobs/",
        "schedules": "/api/v2/job_templates/7/schedules/",
        "activity_stream": "/api/v2/job_templates/7/activity_stream/",
        "launch": "/api/v2/job_templates/7/launch/",
        "webhook_key": "/api/v2/job_templates/7/webhook_key/",
        "webhook_receiver": "",
        "notification_templates_started": "/api/v2/job_templates/7/notification_templates_started/",
        "notification_templates_success": "/api/v2/job_templates/7/notification_templates_success/",
        "notification_templates_error": "/api/v2/job_templates/7/notification_templates_error/",
        "access_list": "/api/v2/job_templates/7/access_list/",
        "survey_spec": "/api/v2/job_templates/7/survey_spec/",
        "object_roles": "/api/v2/job_templates/7/object_roles/",
        "instance_groups": "/api/v2/job_templates/7/instance_groups/",
        "slice_workflow_jobs": "/api/v2/job_templates/7/slice_workflow_jobs/",
        "copy": "/api/v2/job_templates/7/copy/"
      },
      "summary_fields": {
        "organization": {
          "id": 1,
          "name": "Default",
          "description": ""
        },
        "inventory": {
          "id": 1,
          "name": "Demo Inventory",
          "description": "",
          "has_active_failures": false,
          "total_hosts": 1,
          "hosts_with_active_failures": 0,
          "total_groups": 0,
          "has_inventory_sources": false,
          "total_inventory_sources": 0,
          "inventory_sources_with_failures": 0,
          "organization_id": 1,
          "kind": ""
        },
        "project": {
          "id": 6,
          "name": "Demo Project",
          "description": "",
          "status": "successful",
          "scm_type": "git",
          "allow_override": false
        },
        "last_job": {
          "id": 18,
          "name": "Demo Job Template",
          "description": "",
          "finished": "2024-03-15T12:21:31.648339Z",
          "status": "successful",
          "failed": false
        },
        "last_update": {
          "id": 18,
          "name": "Demo Job Template",
          "description": "",
          "status": "successful",
          "failed": false
        },
        "created_by": {
          "id": 1,
          "username": "admin",
          "first_name": "",
          "last_name": ""
        },
        "modified_by": {
          "id": 1,
          "username": "admin",
          "first_name": "",
          "last_name": ""
        },
        "object_roles": {
          "admin_role": {
            "description": "Can manage all aspects of the job template",
            "name": "Admin",
            "id": 37
          },
          "execute_role": {
            "description": "May run the job template",
            "name": "Execute",
            "id": 38
          },
          "read_role": {
            "description": "May view settings for the job template",
            "name": "Read",
            "id": 39
          }
        },
        "user_capabilities": {
          "edit": true,
          "delete": true,
          "start": true,
          "schedule": true,
          "copy": true
        },
        "labels": {
          "count": 0,
          "results": []
        },
        "recent_jobs": [
          {
            "id": 18,
            "status": "successful",
            "finished": "2024-03-15T12:21:31.648339Z",
            "canceled_on": null,
            "type": "job"
          },
          {
            "id": 1,
            "status": "successful",
            "finished": "2024-02-16T00:15:25.600100Z",
            "canceled_on": null,
            "type": "job"
          }
        ],
        "credentials": [
          {
            "id": 1,
            "name": "Demo Credential",
            "description": "",
            "kind": "ssh",
            "cloud": false
          }
        ]
      },
      "created": "2024-02-16T00:06:03.362775Z",
      "modified": "2024-02-16T00:06:03.362794Z",
      "name": "Demo Job Template",
      "description": "",
      "job_type": "run",
      "inventory": 1,
      "project": 6,
      "playbook": "hello_world.yml",
      "scm_branch": "",
      "forks": 0,
      "limit": "",
      "verbosity": 0,
      "extra_vars": "",
      "job_tags": "",
      "force_handlers": false,
      "skip_tags": "",
      "start_at_task": "",
      "timeout": 0,
      "use_fact_cache": false,
      "organization": 1,
      "last_job_run": "2024-03-15T12:21:31.648339Z",
      "last_job_failed": false,
      "next_job_run": null,
      "status": "successful",
      "execution_environment": null,
      "host_config_key": "",
      "ask_scm_branch_on_launch": false,
      "ask_diff_mode_on_launch": false,
      "ask_variables_on_launch": false,
      "ask_limit_on_launch": false,
      "ask_tags_on_launch": false,
      "ask_skip_tags_on_launch": false,
      "ask_job_type_on_launch": false,
      "ask_verbosity_on_launch": false,
      "ask_inventory_on_launch": false,
      "ask_credential_on_launch": false,
      "ask_execution_environment_on_launch": false,
      "ask_labels_on_launch": false,
      "ask_forks_on_launch": false,
      "ask_job_slice_count_on_launch": false,
      "ask_timeout_on_launch": false,
      "ask_instance_groups_on_launch": false,
      "survey_enabled": false,
      "become_enabled": false,
      "diff_mode": false,
      "allow_simultaneous": false,
      "custom_virtualenv": null,
      "job_slice_count": 1,
      "webhook_service": "",
      "webhook_credential": null,
      "prevent_instance_group_fallback": false
    },
    {
      "id": 9,
      "type": "job_template",
      "url": "/api/v2/job_templates/9/",
      "related": {
        "created_by": "/api/v2/users/1/",
        "modified_by": "/api/v2/users/1/",
        "labels": "/api/v2/job_templates/9/labels/",
        "inventory": "/api/v2/inventories/2/",
        "project": "/api/v2/projects/8/",
        "organization": "/api/v2/organizations/1/",
        "credentials": "/api/v2/job_templates/9/credentials/",
        "last_job": "/api/v2/jobs/17/",
        "jobs": "/api/v2/job_templates/9/jobs/",
        "schedules": "/api/v2/job_templates/9/schedules/",
        "activity_stream": "/api/v2/job_templates/9/activity_stream/",
        "launch": "/api/v2/job_templates/9/launch/",
        "webhook_key": "/api/v2/job_templates/9/webhook_key/",
        "webhook_receiver": "",
        "notification_templates_started": "/api/v2/job_templates/9/notification_templates_started/",
        "notification_templates_success": "/api/v2/job_templates/9/notification_templates_success/",
        "notification_templates_error": "/api/v2/job_templates/9/notification_templates_error/",
        "access_list": "/api/v2/job_templates/9/access_list/",
        "survey_spec": "/api/v2/job_templates/9/survey_spec/",
        "object_roles": "/api/v2/job_templates/9/object_roles/",
        "instance_groups": "/api/v2/job_templates/9/instance_groups/",
        "slice_workflow_jobs": "/api/v2/job_templates/9/slice_workflow_jobs/",
        "copy": "/api/v2/job_templates/9/copy/"
      },
      "summary_fields": {
        "organization": {
          "id": 1,
          "name": "Default",
          "description": ""
        },
        "inventory": {
          "id": 2,
          "name": "NGINX inventory",
          "description": "",
          "has_active_failures": true,
          "total_hosts": 1,
          "hosts_with_active_failures": 1,
          "total_groups": 0,
          "has_inventory_sources": false,
          "total_inventory_sources": 0,
          "inventory_sources_with_failures": 0,
          "organization_id": 1,
          "kind": ""
        },
        "project": {
          "id": 8,
          "name": "Развертывание NGINX",
          "description": "",
          "status": "successful",
          "scm_type": "git",
          "allow_override": false
        },
        "last_job": {
          "id": 17,
          "name": "Развертывание NGINX",
          "description": "",
          "finished": "2024-03-15T12:11:55.017427Z",
          "status": "failed",
          "failed": true
        },
        "last_update": {
          "id": 17,
          "name": "Развертывание NGINX",
          "description": "",
          "status": "failed",
          "failed": true
        },
        "created_by": {
          "id": 1,
          "username": "admin",
          "first_name": "",
          "last_name": ""
        },
        "modified_by": {
          "id": 1,
          "username": "admin",
          "first_name": "",
          "last_name": ""
        },
        "object_roles": {
          "admin_role": {
            "description": "Can manage all aspects of the job template",
            "name": "Admin",
            "id": 64
          },
          "execute_role": {
            "description": "May run the job template",
            "name": "Execute",
            "id": 65
          },
          "read_role": {
            "description": "May view settings for the job template",
            "name": "Read",
            "id": 66
          }
        },
        "user_capabilities": {
          "edit": true,
          "delete": true,
          "start": true,
          "schedule": true,
          "copy": true
        },
        "labels": {
          "count": 0,
          "results": []
        },
        "recent_jobs": [
          {
            "id": 17,
            "status": "failed",
            "finished": "2024-03-15T12:11:55.017427Z",
            "canceled_on": null,
            "type": "job"
          }
        ],
        "credentials": []
      },
      "created": "2024-03-15T12:11:27.168941Z",
      "modified": "2024-03-15T12:11:27.168956Z",
      "name": "Развертывание NGINX",
      "description": "",
      "job_type": "run",
      "inventory": 2,
      "project": 8,
      "playbook": "nginx/site.yml",
      "scm_branch": "",
      "forks": 0,
      "limit": "",
      "verbosity": 0,
      "extra_vars": "---",
      "job_tags": "",
      "force_handlers": false,
      "skip_tags": "",
      "start_at_task": "",
      "timeout": 0,
      "use_fact_cache": false,
      "organization": 1,
      "last_job_run": "2024-03-15T12:11:55.017427Z",
      "last_job_failed": true,
      "next_job_run": null,
      "status": "failed",
      "execution_environment": null,
      "host_config_key": "",
      "ask_scm_branch_on_launch": false,
      "ask_diff_mode_on_launch": false,
      "ask_variables_on_launch": false,
      "ask_limit_on_launch": false,
      "ask_tags_on_launch": false,
      "ask_skip_tags_on_launch": false,
      "ask_job_type_on_launch": false,
      "ask_verbosity_on_launch": false,
      "ask_inventory_on_launch": false,
      "ask_credential_on_launch": false,
      "ask_execution_environment_on_launch": false,
      "ask_labels_on_launch": false,
      "ask_forks_on_launch": false,
      "ask_job_slice_count_on_launch": false,
      "ask_timeout_on_launch": false,
      "ask_instance_groups_on_launch": false,
      "survey_enabled": false,
      "become_enabled": false,
      "diff_mode": false,
      "allow_simultaneous": false,
      "custom_virtualenv": null,
      "job_slice_count": 1,
      "webhook_service": "",
      "webhook_credential": null,
      "prevent_instance_group_fallback": false
    }
  ]
}

Запуск задания из шаблона:

curl -X POST --user <admin>:<password> -k https://<address>/api/v2/job_templates/7/launch/ | jq .

Пример вывода команды:

{
  "job": 26,
  "ignored_fields": {},
  "id": 26,
  "type": "job",
  "url": "/api/v2/jobs/26/",
  "related": {
    "created_by": "/api/v2/users/1/",
    "modified_by": "/api/v2/users/1/",
    "labels": "/api/v2/jobs/26/labels/",
    "inventory": "/api/v2/inventories/1/",
    "project": "/api/v2/projects/6/",
    "organization": "/api/v2/organizations/1/",
    "credentials": "/api/v2/jobs/26/credentials/",
    "unified_job_template": "/api/v2/job_templates/7/",
    "stdout": "/api/v2/jobs/26/stdout/",
    "job_events": "/api/v2/jobs/26/job_events/",
    "job_host_summaries": "/api/v2/jobs/26/job_host_summaries/",
    "activity_stream": "/api/v2/jobs/26/activity_stream/",
    "notifications": "/api/v2/jobs/26/notifications/",
    "create_schedule": "/api/v2/jobs/26/create_schedule/",
    "job_template": "/api/v2/job_templates/7/",
    "cancel": "/api/v2/jobs/26/cancel/",
    "relaunch": "/api/v2/jobs/26/relaunch/"
  },
  "summary_fields": {
    "organization": {
      "id": 1,
      "name": "Default",
      "description": ""
    },
    "inventory": {
      "id": 1,
      "name": "Demo Inventory",
      "description": "",
      "has_active_failures": false,
      "total_hosts": 1,
      "hosts_with_active_failures": 0,
      "total_groups": 0,
      "has_inventory_sources": false,
      "total_inventory_sources": 0,
      "inventory_sources_with_failures": 0,
      "organization_id": 1,
      "kind": ""
    },
    "project": {
      "id": 6,
      "name": "Demo Project",
      "description": "",
      "status": "successful",
      "scm_type": "git",
      "allow_override": false
    },
    "job_template": {
      "id": 7,
      "name": "Demo Job Template",
      "description": ""
    },
    "unified_job_template": {
      "id": 7,
      "name": "Demo Job Template",
      "description": "",
      "unified_job_type": "job"
    },
    "created_by": {
      "id": 1,
      "username": "admin",
      "first_name": "",
      "last_name": ""
    },
    "modified_by": {
      "id": 1,
      "username": "admin",
      "first_name": "",
      "last_name": ""
    },
    "user_capabilities": {
      "delete": true,
      "start": true
    },
    "labels": {
      "count": 0,
      "results": []
    },
    "credentials": [
      {
        "id": 1,
        "name": "Demo Credential",
        "description": "",
        "kind": "ssh",
        "cloud": false
      }
    ]
  },
  "created": "2024-03-19T06:41:24.347473Z",
  "modified": "2024-03-19T06:41:24.389125Z",
  "name": "Demo Job Template",
  "description": "",
  "job_type": "run",
  "inventory": 1,
  "project": 6,
  "playbook": "hello_world.yml",
  "scm_branch": "",
  "forks": 0,
  "limit": "",
  "verbosity": 0,
  "extra_vars": "{}",
  "job_tags": "",
  "force_handlers": false,
  "skip_tags": "",
  "start_at_task": "",
  "timeout": 0,
  "use_fact_cache": false,
  "organization": 1,
  "unified_job_template": 7,
  "launch_type": "manual",
  "status": "pending",
  "execution_environment": null,
  "failed": false,
  "started": null,
  "finished": null,
  "canceled_on": null,
  "elapsed": 0,
  "job_args": "",
  "job_cwd": "",
  "job_env": {},
  "job_explanation": "",
  "execution_node": "",
  "controller_node": "",
  "result_traceback": "",
  "event_processing_finished": false,
  "launched_by": {
    "id": 1,
    "name": "admin",
    "type": "user",
    "url": "/api/v2/users/1/"
  },
  "work_unit_id": null,
  "job_template": 7,
  "passwords_needed_to_start": [],
  "allow_simultaneous": false,
  "artifacts": {},
  "scm_revision": "",
  "instance_group": null,
  "diff_mode": false,
  "job_slice_number": 0,
  "job_slice_count": 1,
  "webhook_service": "",
  "webhook_credential": null,
  "webhook_guid": ""
}

Получение токена авторизации:

curl -X POST \
https://<address>/api/v2/tokens/ \
-H 'Content-Type: application/json' \
-d '{
      "description": "Token description",
      "application": null,
      "user": "admin",
      "scope": "write"
   }' \
-u '<admin>:<password>' | jq .

Проверка статуса задания, запущенного ранее:

curl -X GET \
https://<address>/api/v2/jobs/<jobs_id>/ \
-H 'Authorization: Bearer <your_token>' \
-k -s | jq .

Здесь <jobs_id> – идентификатор задания, запущенного ранее.

Пример вывода команды:

{
  "id": 26,
  "type": "job",
  "url": "/api/v2/jobs/26/",
  "related": {
    "created_by": "/api/v2/users/1/",
    "labels": "/api/v2/jobs/26/labels/",
    "inventory": "/api/v2/inventories/1/",
    "project": "/api/v2/projects/6/",
    "organization": "/api/v2/organizations/1/",
    "credentials": "/api/v2/jobs/26/credentials/",
    "unified_job_template": "/api/v2/job_templates/7/",
    "stdout": "/api/v2/jobs/26/stdout/",
    "execution_environment": "/api/v2/execution_environments/1/",
    "job_events": "/api/v2/jobs/26/job_events/",
    "job_host_summaries": "/api/v2/jobs/26/job_host_summaries/",
    "activity_stream": "/api/v2/jobs/26/activity_stream/",
    "notifications": "/api/v2/jobs/26/notifications/",
    "create_schedule": "/api/v2/jobs/26/create_schedule/",
    "job_template": "/api/v2/job_templates/7/",
    "cancel": "/api/v2/jobs/26/cancel/",
    "relaunch": "/api/v2/jobs/26/relaunch/"
  },
  "summary_fields": {
    "organization": {
      "id": 1,
      "name": "Default",
      "description": ""
    },
    "inventory": {
      "id": 1,
      "name": "Demo Inventory",
      "description": "",
      "has_active_failures": false,
      "total_hosts": 1,
      "hosts_with_active_failures": 0,
      "total_groups": 0,
      "has_inventory_sources": false,
      "total_inventory_sources": 0,
      "inventory_sources_with_failures": 0,
      "organization_id": 1,
      "kind": ""
    },
    "execution_environment": {
      "id": 1,
      "name": "Default execution environment",
      "description": "",
      "image": "registry.astralinux.ru/aa/aa-base-ee:0.2.1"
    },
    "project": {
      "id": 6,
      "name": "Demo Project",
      "description": "",
      "status": "successful",
      "scm_type": "git",
      "allow_override": false
    },
    "job_template": {
      "id": 7,
      "name": "Demo Job Template",
      "description": ""
    },
    "unified_job_template": {
      "id": 7,
      "name": "Demo Job Template",
      "description": "",
      "unified_job_type": "job"
    },
    "instance_group": {
      "id": 1,
      "name": "controlplane",
      "is_container_group": false
    },
    "created_by": {
      "id": 1,
      "username": "admin",
      "first_name": "",
      "last_name": ""
    },
    "user_capabilities": {
      "delete": true,
      "start": true
    },
    "labels": {
      "count": 0,
      "results": []
    },
    "credentials": [
      {
        "id": 1,
        "name": "Demo Credential",
        "description": "",
        "kind": "ssh",
        "cloud": false
      }
    ]
  },
  "created": "2024-03-19T06:41:24.347473Z",
  "modified": "2024-03-19T06:41:24.596205Z",
  "name": "Demo Job Template",
  "description": "",
  "job_type": "run",
  "inventory": 1,
  "project": 6,
  "playbook": "hello_world.yml",
  "scm_branch": "",
  "forks": 0,
  "limit": "",
  "verbosity": 0,
  "extra_vars": "{}",
  "job_tags": "",
  "force_handlers": false,
  "skip_tags": "",
  "start_at_task": "",
  "timeout": 0,
  "use_fact_cache": false,
  "organization": 1,
  "unified_job_template": 7,
  "launch_type": "manual",
  "status": "successful",
  "execution_environment": 1,
  "failed": false,
  "started": "2024-03-19T06:41:24.694396Z",
  "finished": "2024-03-19T06:41:28.962513Z",
  "canceled_on": null,
  "elapsed": 4.268,
  "job_args": "[\"podman\", \"run\", \"--rm\", \"--tty\", \"--interactive\", \"--workdir\", \"/runner/project\", \"-v\", \"/tmp/awx_26_b59w6psk/:/runner/:Z\", \"--env-file\", \"/tmp/awx_26_b59w6psk/artifacts/26/env.list\", \"--quiet\", \"--name\", \"ansible_runner_26\", \"--user=root\", \"--network\", \"slirp4netns:enable_ipv6=true\", \"registry.astralinux.ru/aa/aa-base-ee:0.2.1\", \"ansible-playbook\", \"-u\", \"admin\", \"-i\", \"/runner/inventory/hosts\", \"-e\", \"@/runner/env/extravars\", \"hello_world.yml\"]",
  "job_cwd": "/runner/project",
  "job_env": {
    "ANSIBLE_UNSAFE_WRITES": "1",
    "AWX_ISOLATED_DATA_DIR": "/runner/artifacts/26",
    "ANSIBLE_FORCE_COLOR": "True",
    "ANSIBLE_HOST_KEY_CHECKING": "False",
    "ANSIBLE_INVENTORY_UNPARSED_FAILED": "True",
    "ANSIBLE_PARAMIKO_RECORD_HOST_KEYS": "False",
    "HOME": "/var/lib/awx",
    "AWX_PRIVATE_DATA_DIR": "/tmp/awx_26_b59w6psk",
    "JOB_ID": "26",
    "INVENTORY_ID": "1",
    "PROJECT_REVISION": "347e44fea036c94d5f60e544de006453ee5c71ad",
    "ANSIBLE_RETRY_FILES_ENABLED": "False",
    "MAX_EVENT_RES": "700000",
    "AWX_HOST": "https://controller",
    "ANSIBLE_SSH_CONTROL_PATH_DIR": "/runner/cp",
    "ANSIBLE_COLLECTIONS_PATHS": "/runner/requirements_collections:~/.ansible/collections:/usr/share/ansible/collections",
    "ANSIBLE_ROLES_PATH": "/runner/requirements_roles:~/.ansible/roles:/usr/share/ansible/roles:/etc/ansible/roles",
    "ANSIBLE_CALLBACK_PLUGINS": "/runner/artifacts/26/callback",
    "ANSIBLE_STDOUT_CALLBACK": "awx_display",
    "RUNNER_OMIT_EVENTS": "False",
    "RUNNER_ONLY_FAILED_EVENTS": "False"
  },
  "job_explanation": "",
  "execution_node": "192.168.56.11",
  "controller_node": "192.168.56.11",
  "result_traceback": "",
  "event_processing_finished": true,
  "launched_by": {
    "id": 1,
    "name": "admin",
    "type": "user",
    "url": "/api/v2/users/1/"
  },
  "work_unit_id": "Vt4HYQqA",
  "job_template": 7,
  "passwords_needed_to_start": [],
  "allow_simultaneous": false,
  "artifacts": {},
  "scm_revision": "347e44fea036c94d5f60e544de006453ee5c71ad",
  "instance_group": 1,
  "diff_mode": false,
  "job_slice_number": 0,
  "job_slice_count": 1,
  "webhook_service": "",
  "webhook_credential": null,
  "webhook_guid": "",
  "host_status_counts": {
    "ok": 1
  },
  "playbook_counts": {
    "play_count": 1,
    "task_count": 2
  },
  "custom_virtualenv": null
}

Создание проекта:

curl -X POST \
https://<address>/api/v2/projects/ \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{
   "name": "New Project",
   "organization": 1,
   "scm_type": "git",
   "scm_url": "https://github.com/ansible/ansible-tower-samples"
}' \
-k -s | jq .

Пример вывода команды:

{
  "id": 13,
  "type": "project",
  "url": "/api/v2/projects/13/",
  "related": {
    "named_url": "/api/v2/projects/New Project++Default/",
    "created_by": "/api/v2/users/1/",
    "modified_by": "/api/v2/users/1/",
    "current_job": "/api/v2/project_updates/29/",
    "teams": "/api/v2/projects/13/teams/",
    "playbooks": "/api/v2/projects/13/playbooks/",
    "inventory_files": "/api/v2/projects/13/inventories/",
    "update": "/api/v2/projects/13/update/",
    "project_updates": "/api/v2/projects/13/project_updates/",
    "scm_inventory_sources": "/api/v2/projects/13/scm_inventory_sources/",
    "schedules": "/api/v2/projects/13/schedules/",
    "activity_stream": "/api/v2/projects/13/activity_stream/",
    "notification_templates_started": "/api/v2/projects/13/notification_templates_started/",
    "notification_templates_success": "/api/v2/projects/13/notification_templates_success/",
    "notification_templates_error": "/api/v2/projects/13/notification_templates_error/",
    "access_list": "/api/v2/projects/13/access_list/",
    "object_roles": "/api/v2/projects/13/object_roles/",
    "copy": "/api/v2/projects/13/copy/",
    "organization": "/api/v2/organizations/1/",
    "current_update": "/api/v2/project_updates/29/"
  },
  "summary_fields": {
    "organization": {
      "id": 1,
      "name": "Default",
      "description": ""
    },
    "current_update": {
      "id": 29,
      "name": "New Project",
      "description": "",
      "status": "pending",
      "failed": false
    },
    "current_job": {
      "id": 29,
      "name": "New Project",
      "description": "",
      "status": "pending",
      "failed": false
    },
    "created_by": {
      "id": 1,
      "username": "admin",
      "first_name": "",
      "last_name": ""
    },
    "modified_by": {
      "id": 1,
      "username": "admin",
      "first_name": "",
      "last_name": ""
    },
    "object_roles": {
      "admin_role": {
        "description": "Can manage all aspects of the project",
        "name": "Admin",
        "id": 79
      },
      "use_role": {
        "description": "Can use the project in a job template",
        "name": "Use",
        "id": 80
      },
      "update_role": {
        "description": "May update the project",
        "name": "Update",
        "id": 81
      },
      "read_role": {
        "description": "May view settings for the project",
        "name": "Read",
        "id": 82
      }
    },
    "user_capabilities": {
      "edit": true,
      "delete": true,
      "start": true,
      "schedule": true,
      "copy": true
    }
  },
  "created": "2024-03-19T14:26:16.980872Z",
  "modified": "2024-03-19T14:26:16.980886Z",
  "name": "New Project",
  "description": "",
  "local_path": "_13__new_project",
  "scm_type": "git",
  "scm_url": "https://github.com/ansible/ansible-tower-samples",
  "scm_branch": "",
  "scm_refspec": "",
  "scm_clean": false,
  "scm_track_submodules": false,
  "scm_delete_on_update": false,
  "credential": null,
  "timeout": 0,
  "scm_revision": "",
  "last_job_run": null,
  "last_job_failed": false,
  "next_job_run": null,
  "status": "pending",
  "organization": 1,
  "scm_update_on_launch": false,
  "scm_update_cache_timeout": 0,
  "allow_override": false,
  "custom_virtualenv": null,
  "default_environment": null,
  "signature_validation_credential": null,
  "last_update_failed": false,
  "last_updated": null
}

Изменение проекта, созданного ранее:

curl -X PATCH \
https://<address>/api/v2/projects/<project_id>/ \
-H 'Authorization: Bearer <your_token>' \
-H 'Content-Type: application/json' \
-d '{
   "name": "Updated Project",
   "scm_url": "https://github.com/ansible/ansible-examples"
}' \
-k -s | jq .

Здесь <project_id> – идентификатор проекта, созданного ранее.

Пример вывода команды:

{
  "id": 13,
  "type": "project",
  "url": "/api/v2/projects/13/",
  "related": {
    "named_url": "/api/v2/projects/Updated Project++Default/",
    "created_by": "/api/v2/users/1/",
    "modified_by": "/api/v2/users/1/",
    "current_job": "/api/v2/project_updates/30/",
    "last_job": "/api/v2/project_updates/29/",
    "teams": "/api/v2/projects/13/teams/",
    "playbooks": "/api/v2/projects/13/playbooks/",
    "inventory_files": "/api/v2/projects/13/inventories/",
    "update": "/api/v2/projects/13/update/",
    "project_updates": "/api/v2/projects/13/project_updates/",
    "scm_inventory_sources": "/api/v2/projects/13/scm_inventory_sources/",
    "schedules": "/api/v2/projects/13/schedules/",
    "activity_stream": "/api/v2/projects/13/activity_stream/",
    "notification_templates_started": "/api/v2/projects/13/notification_templates_started/",
    "notification_templates_success": "/api/v2/projects/13/notification_templates_success/",
    "notification_templates_error": "/api/v2/projects/13/notification_templates_error/",
    "access_list": "/api/v2/projects/13/access_list/",
    "object_roles": "/api/v2/projects/13/object_roles/",
    "copy": "/api/v2/projects/13/copy/",
    "organization": "/api/v2/organizations/1/",
    "current_update": "/api/v2/project_updates/30/",
    "last_update": "/api/v2/project_updates/29/"
  },
  "summary_fields": {
    "organization": {
      "id": 1,
      "name": "Default",
      "description": ""
    },
    "last_job": {
      "id": 29,
      "name": "New Project",
      "description": "",
      "finished": "2024-03-19T14:26:21.930637Z",
      "status": "successful",
      "failed": false
    },
    "last_update": {
      "id": 29,
      "name": "New Project",
      "description": "",
      "status": "successful",
      "failed": false
    },
    "current_update": {
      "id": 30,
      "name": "Updated Project",
      "description": "",
      "status": "pending",
      "failed": false
    },
    "current_job": {
      "id": 30,
      "name": "Updated Project",
      "description": "",
      "status": "pending",
      "failed": false
    },
    "created_by": {
      "id": 1,
      "username": "admin",
      "first_name": "",
      "last_name": ""
    },
    "modified_by": {
      "id": 1,
      "username": "admin",
      "first_name": "",
      "last_name": ""
    },
    "object_roles": {
      "admin_role": {
        "description": "Can manage all aspects of the project",
        "name": "Admin",
        "id": 79
      },
      "use_role": {
        "description": "Can use the project in a job template",
        "name": "Use",
        "id": 80
      },
      "update_role": {
        "description": "May update the project",
        "name": "Update",
        "id": 81
      },
      "read_role": {
        "description": "May view settings for the project",
        "name": "Read",
        "id": 82
      }
    },
    "user_capabilities": {
      "edit": true,
      "delete": true,
      "start": true,
      "schedule": true,
      "copy": true
    },
    "resolved_environment": {
      "id": 1,
      "name": "Default execution environment",
      "description": "",
      "image": "registry.astralinux.ru/aa/aa-base-ee:0.2.1"
    }
  },
  "created": "2024-03-19T14:26:16.980872Z",
  "modified": "2024-03-19T14:28:32.951463Z",
  "name": "Updated Project",
  "description": "",
  "local_path": "_13__new_project",
  "scm_type": "git",
  "scm_url": "https://github.com/ansible/ansible-examples",
  "scm_branch": "",
  "scm_refspec": "",
  "scm_clean": false,
  "scm_track_submodules": false,
  "scm_delete_on_update": false,
  "credential": null,
  "timeout": 0,
  "scm_revision": "347e44fea036c94d5f60e544de006453ee5c71ad",
  "last_job_run": "2024-03-19T14:26:21.930637Z",
  "last_job_failed": false,
  "next_job_run": null,
  "status": "pending",
  "organization": 1,
  "scm_update_on_launch": false,
  "scm_update_cache_timeout": 0,
  "allow_override": false,
  "custom_virtualenv": null,
  "default_environment": null,
  "signature_validation_credential": null,
  "last_update_failed": false,
  "last_updated": "2024-03-19T14:26:21.930637Z"
}

Удаление проекта:

curl -X DELETE \
https://<address>/api/v2/projects/<project_id>/ \
-H 'Authorization: Bearer <your-token>'

Расширения для браузера#

Применение расширения для браузера Google Chrome выглядит следующим образом:

Откройте Chrome Web Store и установите расширение Postman на ваш браузер.
Запустите Postman из списка расширений в вашем браузере.
Создайте новый запрос.
Введите URI объекта, который вы хотите запросить, и выберите нужный метод HTTP (GET, POST, PUT, PATCH, DELETE).
Отправьте запрос.
После отправки запроса вы увидите ответ от сервера в формате JSON, XML или другом формате. Вы также можете просмотреть статус-код ответа и другие детали.

Программа на языке программирования#

Рассмотрим в качестве примера скрипт Python, который выполняет следующие действия в контроллере:

Создает новый проект.
Получает информацию о всех проектах.
Получает информацию о созданном проекте.
Обновляет проект из источника.
Проверяет статус обновления проекта.
Изменяет проект.
Получает информацию о созданом проекте после изменения.
Удаляет проект.
Получает информацию о всех проектах.
Получает конфигурацию Astra Automation Controller.

После команд, запускающих какое-либо действие на сервере, добавлена тридцатисекундная пауза для наглядности выполнения команд.

Для запуска скрипта необходимо:

Использовать Python не ниже версии 3.8.
Установить пакет requests.

"""Demo scenario"""

import json
import time
import requests

# Define base URL and headers
base_url = "https://<address>/api/v2/"
headers = {"Authorization": "Bearer <your_token>", "Content-type": "application/json"}


def button_press():
    """Prompt the user to press Enter to continue."""
    input("\nНажмите Enter чтобы продолжить...\n")


def print_json(response):
    """
    Print the response JSON returned by a REST API request.

    Args:
        response: The response object returned by the REST API request
    """
    if response.text:
        print(json.dumps(response.json(), indent=4))
    else:
        print("Status code:", response.status_code)


# Define the project data
project_data = {
    "name": "New Project",
    "organization": 1,
    "scm_type": "git",
    "scm_url": "https://github.com/ansible/ansible-tower-samples",
}

# Post new project
response_post_new_project = requests.post(
    f"{base_url}projects/",
    headers=headers,
    data=json.dumps(project_data),
    verify=False,
    timeout=10,
)
print("\n--- Создание проекта ---")
print_json(response_post_new_project)
project_id = response_post_new_project.json()["id"]
time.sleep(30)
print("\n --- Проект создан ---")
button_press()

# Get all projects
response_get_all_projects = requests.get(
    f"{base_url}projects/", headers=headers, verify=False, timeout=10
)
print("\n--- Информация о проектах ---")
print_json(response_get_all_projects)
print("\n --- Выведена информация по всем проектам ---")
button_press()

# Get project details
response_get_project_detail = requests.get(
    f"{base_url}projects/{project_id}/", headers=headers, verify=False, timeout=10
)
print("\n--- Получение деталей проекта ---")
print_json(response_get_project_detail)
print("\n --- Выведена информация о созданном проекте ---")
button_press()

# Update project from the version control source
response_update_project = requests.post(
    f"{base_url}projects/{project_id}/update/",
    headers=headers,
    verify=False,
    timeout=10,
)
print("\n--- Обновление проекта из источника контроля версий ---")
print_json(response_update_project)
time.sleep(30)
print("\n --- Проект обновлен ---")
button_press()

# Check update status information
response_project_update_status = requests.get(
    f"{base_url}projects/{project_id}/project_updates/",
    headers=headers,
    verify=False,
    timeout=10,
)
print("\n--- Проверка информации о статусе обновления ---")
print_json(response_project_update_status)
print("\n --- Выведена информация о статусе обновления ---")
button_press()

# Change the project
patch_data = {
    "name": "Updated Project",
    "scm_url": "https://github.com/ansible/ansible-examples",
}
response_patch_project = requests.patch(
    f"{base_url}projects/{project_id}/",
    headers=headers,
    data=json.dumps(patch_data),
    verify=False,
    timeout=10,
)
print("\n--- Изменение проекта ---")
print_json(response_patch_project)
time.sleep(30)
print("\n --- Проект изменён ---")
button_press()

# Get project details after the change
response_get_project_detail_after_change = requests.get(
    f"{base_url}projects/{project_id}/", headers=headers, verify=False, timeout=10
)
print("\n--- Получение деталей проекта (после обновления) ---")
print_json(response_get_project_detail_after_change)
print("\n --- Выведена информация о созданном проекте после изменения ---")
button_press()

# Delete the project
response_delete_project = requests.delete(
    f"{base_url}projects/{project_id}/", headers=headers, verify=False, timeout=10
)
print("\n--- Удаление проекта ---")
print_json(response_delete_project)
print("\n --- Проект удалён ---")
button_press()

# List all projects after deletion
response_get_all_projects_after_deletion = requests.get(
    f"{base_url}projects/", headers=headers, verify=False, timeout=10
)
print("\n--- Список проектов (после удаления) ---")
print_json(response_get_all_projects_after_deletion)
print("\n --- Выведена информация по всем проектам после удаления ---")
button_press()

# Get Astra Automation Controller Configuration
response_get_configuration = requests.get(
    f"{base_url}config/", headers=headers, verify=False, timeout=10
)
print("\n--- Получение конфигурации Astra Automation Controller ---")
print_json(response_get_configuration)
print("\n --- Выведена информация по серверу Astra Automation Controller ---")

В демонстрационном скрипте замените значения <address> и <your_token> на свои.

Клиенты API

Содержание

Клиенты API#

Браузер#

Утилита curl#

Примеры использования curl#

Расширения для браузера#

Программа на языке программирования#