자동화 실행 API 개요

지정된 값과 일치하는 항목으로 반환된 결과 목록을 필터링하는 데 사용되는 추가 쿼리 문자열 매개변수를 사용할 수 있습니다. 필터링을 위해 데이터베이스에 존재하는 필드 및 관계만 사용할 수 있습니다.

지정된 값의 특수 문자가 URL로 인코딩되었는지 확인합니다. 예를 들면 다음과 같습니다.

?field=value%20xyz

?field=value%20xyz

필드는 데이터베이스에 정의된 필드 및 관계에 대해서만 관계를 확장할 수도 있습니다.

?other__field=value

?other__field=value

특정 기준과 일치하는 결과를 제외하려면 field 매개변수 앞에 not__: 접두사를 지정합니다.

?not__field=value

?not__field=value

기본적으로 모든 쿼리 문자열 필터는 AND로 연결되므로 모든 필터와 일치하는 결과만 반환됩니다. 여러 조건 중 하나와 일치하는 결과를 결합하려면 각 쿼리 문자열 매개변수 앞에 or__ 를 붙입니다.

?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue

?or__field=value&or__field=othervalue
?or__not__field=value&or__field=othervalue

기본 AND 필터링에서는 여러 데이터베이스 관계에 걸쳐 필터링되는 각 관련 오브젝트에 모든 필터를 동시에 적용합니다. 반면 체인 필터는 각 관련 오브젝트에 필터를 개별적으로 적용합니다. 이를 사용하려면 query 문자열 매개변수 앞에 chain__: 접두사를 붙입니다.

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&chain__related__field2=othervalue

첫 번째 쿼리를 ? 관련field=value&relatedfield2=othervalue 로 작성하는 경우 관련 개체가 두 조건을 모두 충족하는 기본 오브젝트만 반환합니다. 체인 필터를 사용하여 작성된 대로 각 조건과 일치하는 기본 오브젝트의 교집합을 반환합니다.

필드 조회를 사용하면 특정 기준에 따라 API 결과를 필터링할 수 있습니다. 필드 이름에 조회를 추가하여 고급 쿼리에 필드 조회를 사용할 수 있습니다.

?field__lookup=value

?field__lookup=value

다음과 같은 필드 조회가 지원됩니다.

예를 들어 ?created__gte=2023-01-01 은 1/1/2023 이후에 생성된 항목 목록을 제공합니다.

null 값을 None 또는 Null (둘 다 대소문자를 구분하지 않음)으로 지정할 수 있지만 isnull 조회를 사용하여 null 값을 명시적으로 확인하는 것이 좋습니다.

목록을 쉼표로 구분된 값 목록으로 지정할 수 있습니다. 쿼리 문자열 매개변수를 통해 요청하는 사용자의 액세스 수준을 기준으로 필터링합니다.

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
...

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
...

/api/controller/v2/settings/named-url/: NAMED_URL_FORMATS 및 NAMED_URL_GRAPH_NODES 에서 사용할 수 있는 이름이 지정된 URL 관련 구성 설정은 두 가지가 있습니다.

NAMED_URL_FORMATS 는 이름이 지정된 모든 URL 식별자 형식의 읽기 전용 키-값 쌍 목록입니다. 다음은 NAMED_URL_FORMATS 예제를 보여줍니다.

"NAMED_URL_FORMATS": {
"organizations": "<name>",
"teams": "<name>++<organization.name>",
"credential_types": "<name>+<kind>",
"credentials": "<name>++<credential_type.name>+<credential_type.kind>++<organization.name>",
"notification_templates": "<name>++<organization.name>",
"job_templates": "<name>++<organization.name>",
"projects": "<name>++<organization.name>",
"inventories": "<name>++<organization.name>",
"hosts": "<name>++<inventory.name>++<organization.name>",
"groups": "<name>++<inventory.name>++<organization.name>",
"inventory_sources": "<name>++<inventory.name>++<organization.name>",
"inventory_scripts": "<name>++<organization.name>",
"instance_groups": "<name>",
"labels": "<name>++<organization.name>",
"workflow_job_templates": "<name>++<organization.name>",
"workflow_job_template_nodes": "<identifier>++<workflow_job_template.name>++<organization.name>",
"applications": "<name>++<organization.name>",
"users": "<username>",
"instances": "<hostname>"
}

"NAMED_URL_FORMATS": {
"organizations": "<name>",
"teams": "<name>++<organization.name>",
"credential_types": "<name>+<kind>",
"credentials": "<name>++<credential_type.name>+<credential_type.kind>++<organization.name>",
"notification_templates": "<name>++<organization.name>",
"job_templates": "<name>++<organization.name>",
"projects": "<name>++<organization.name>",
"inventories": "<name>++<organization.name>",
"hosts": "<name>++<inventory.name>++<organization.name>",
"groups": "<name>++<inventory.name>++<organization.name>",
"inventory_sources": "<name>++<inventory.name>++<organization.name>",
"inventory_scripts": "<name>++<organization.name>",
"instance_groups": "<name>",
"labels": "<name>++<organization.name>",
"workflow_job_templates": "<name>++<organization.name>",
"workflow_job_template_nodes": "<identifier>++<workflow_job_template.name>++<organization.name>",
"applications": "<name>++<organization.name>",
"users": "<username>",
"instances": "<hostname>"
}

NAMED_URL_FORMATS 의 각 항목에 대해 키는 이름이 URL인 리소스의 API 이름입니다. 값은 해당 리소스에 대해 사람이 읽을 수 있는 고유 ID를 형성하는 방법을 나타내는 문자열입니다. NAMED_URL_FORMATS 는 이름이 지정된 URL을 포함할 수 있는 리소스만 나열합니다. 여기에 나열되지 않은 리소스에는 이름이 지정된 URL이 없습니다. 리소스에 이름이 지정된 URL이 있을 수 있는 경우 해당 오브젝트에 오브젝트별 이름이 지정된 URL을 나타내는 named_url 필드가 있어야 합니다. 해당 필드는 목록 보기가 아닌 세부 정보 보기에만 표시됩니다. 정확히 생성된 이름이 지정된 URL을 사용하여 지정된 리소스 오브젝트에 액세스할 수 있습니다. 개체 및 관련 URL입니다. 예를 들어 /api/controller/v2/res_name/obj_slug/ 가 유효한 경우 /api/controller/v2/res_name/obj_slug/related_res_name/ 도 유효합니다.

NAMED_URL_FORMATS 는 사람이 읽을 수 있는 고유 식별자와 이름이 지정된 URL을 직접 구성할 수 있을 만큼 권한을 부여합니다. 사용하기 쉽도록 이름이 지정된 URL을 포함할 수 있는 리소스의 모든 오브젝트에는 해당 오브젝트의 이름이 지정된 URL을 표시하는 관련 필드인_url 이 있습니다. 사용자 정의 용도로 해당 필드를 복사하여 붙여넣을 수 있습니다. 자세한 내용은 리소스 오브젝트에 이름이 지정된 URL이 있는 경우 API 브라우저의 도움말 텍스트를 참조하십시오.

이름이 지정된 URL 레이블을 수동으로 결정할 수 있습니다(예: ID 5). NAMED_URL_FORMATS 를 사용하여 이 특정 리소스 오브젝트에 대해 이름이 지정된 URL을 작성하려면 먼저 NAMED_URL_FORMATS 의 labels 필드를 찾아 ID 형식 <name> ++<organization.name>을 가져옵니다.

이름이 지정된 URL에 대한 고유 ID를 생성하는 작업의 중요한 측면은 예약된 문자와 관련이 있습니다. ID가 URL의 일부이므로 URL 표준에 따라 예약된 문자는 백분율 기호로 인코딩됩니다. ;/?@=&[]. 예를 들어 조직 이름이 ;/?:@=&[] 인 경우 고유 식별자는 %3B%3F%3F%3F%3D%5B%5D 여야 합니다. 또 다른 특수 예약 문자는 + 이며 URL 표준에 의해 예약되지는 않지만 이름이 지정된 URL에서 식별자의 다른 부분을 연결하는 데 사용됩니다. [암호]로 인코딩됩니다. 예를 들어 조직 이름이 [ Cryostat )인 경우 고유 식별자는 %5B[#159%5D )입니다. 여기서 original [ 및 ] 은 백분율로 인코딩되고 + 는 []로 변환됩니다.

NAMED_URL_FORMATS 를 수동으로 변경할 수는 없지만 기본 리소스 수정 및 확장을 반영하여 수정 사항이 자동으로 발생하고 시간이 지남에 따라 확장됩니다. 이름이 지정된 URL 기능을 사용하려는 동일한 클러스터에서 NAMED_URL_FORMATS 를 참조하십시오.

NAMED_URL_GRAPH_NODES 는 이름이 지정된 URL을 관리하는 데 사용되는 내부 그래프 데이터 구조를 노출하는 키-값 쌍의 읽기 전용 목록입니다. 이는 사람이 읽을 수 있는 것은 아니지만 이름이 지정된 URL을 프로그래밍 방식으로 생성하는 데 사용해야 합니다. NAMED_URL_GRAPH_NODES 에서 제공하는 정보를 사용하여 이름이 지정된 URL의 기본 키를 기반으로 이름이 지정된 URL을 생성하는 스크립트의 예는 GitHub 에서 찾을 수 있습니다.

자동화 컨트롤러는 일관된 프로토콜을 사용하여 API 및 웹 인터페이스에서 이름으로 처리할 수 있는 리소스에 대해 사람이 읽을 수 있는 고유 ID를 생성합니다.

리소스는 리소스 필드의 튜플인 고유 키로 식별할 수 있습니다. 모든 리소스에는 기본 키 번호만 고유 키로 사용할 수 있지만 다른 고유 키가 많이 있을 수 있습니다. 리소스는 ID 형식을 생성할 수 있으므로 다음 규칙을 충족하는 고유 키가 하나 이상 있는 경우 이름이 지정된 URL이 있습니다.

Foo 및 Bar 리소스가 있는 경우 Foo 및 Bar 에는 "yes" 또는 "no" 값만 가질 수 있는 이름 필드와 선택 필드가 모두 포함되어 있습니다. 또한 리소스 Foo 에는 Bar 와 관련된 다대일 필드(예: fk )가 있습니다. foo 에는 고유한 키 튜플(이름,선택 사항,fk)이 있으며 Bar 에는 고유한 키 튜플(이름,선택)이 있습니다. bar 는 이전 첫 번째 규칙을 충족하기 때문에 이름이 지정된 URL을 포함할 수 있습니다. foo 는 첫 번째 규칙을 위반하더라도 이름이 지정된 URL을 포함할 수도 있습니다. 규칙 번호 1을 위반하는 추가 필드는 Bar 와 Bar와 관련된 many-to-one 필드이며, Bar 는 이름이 지정된 URL을 포함할 수 있습니다.

규칙 번호 1을 충족하는 리소스의 경우 사람이 읽을 수 있는 고유 식별자는 외래 키 필드의 조합이며, + 로 구분됩니다. 구체적으로 위 예제의 리소스 표시줄에는 슬러그 형식 < name>+<choice>가 있습니다.

필드 순서는 슬러그 형식에서 중요하며 이름 필드는 항상 있는 경우 먼저 오고 나머지 필드가 필드 이름의 사전순으로 정렬되어 있습니다. 예를 들어, Bar 에도 규칙 1을 충족하는 a_choice 필드가 있고 고유 키가 있는 경우 (이름 , 선택 , a_choice ) 이면 슬러그 형식은 <name >< a_choice><choice >가 됩니다.

규칙 번호 2를 충족하는 리소스의 경우 추가 외래 키 필드를 역추적하면 결과는 해당 리소스의 오브젝트를 식별하는 리소스 트리입니다. ID 형식을 생성하기 위해 역추적 트리의 각 리소스는 외래 키를 제외한 모든 필드를 사용하여 독립 실행형 형식의 자체 부분을 생성합니다. 마지막으로 모든 부분은 다음과 같은 순서로 ++ 로 결합됩니다.

리소스 Foo 에 대한 식별자 형식을 생성할 때 자동화 컨트롤러는 Foo 및 <fk.name>+<fk. name>+< fk.choice >의 경우 독립형 형식 <name><choice >+<fk. name>+<fk.choice>+<fk.choice >로 결합합니다.

지정된 식별자 형식에 따라 식별자를 생성할 때 외래 키가 위치를 가리키지 않을 수 있는 경우가 있습니다. 이 경우 자동화 컨트롤러는 외래 키가 가리켜야 하는 리소스에 해당하는 형식의 부분을 빈 문자열로 대체합니다. 예를 들어 Foo 오브젝트에 name ="alice", choice ="yes" 가 있지만 fk 필드 = None 이 있는 경우 결과 식별자는 alice+yes++ 입니다.

자동화 컨트롤러의 API 또는 UI에 직접 로그인할 때 세션 인증을 사용하여 인벤토리, 프로젝트, 작업 템플릿과 같은 리소스를 수동으로 생성하고 브라우저에서 작업을 시작할 수 있습니다.

이 방법을 사용하면 해당 HTTP 요청뿐만 아니라 장기간 로그인 상태를 유지할 수 있습니다. 예를 들어 Chrome 또는 Mozilla Firefox와 같은 브라우저에서 API 또는 UI를 검색하는 경우입니다. 로그인하면 세션 쿠키가 생성되면 자동화 컨트롤러 내의 다른 페이지로 이동할 때 로그인 상태를 유지할 수 있습니다.

다음 이미지는 세션의 클라이언트와 서버 간에 발생하는 통신을 나타냅니다.

View larger image

자동화 컨트롤러에 로그인할 때 발생하는 활동을 확인하려면 curl 툴을 사용합니다.

이 모든 작업은 브라우저에서 UI 또는 API에 로그인할 때 자동화 컨트롤러에서 수행하며 브라우저에서 인증할 때만 사용해야 합니다. 자동화 컨트롤러와 프로그래밍 방식의 통합은 OAuth2 토큰 인증을 참조하십시오.

+

Server: nginx
Date: <current date>
Content-Type: text/html; charset=utf-8
Content-Length: 0
Connection: keep-alive
Location: /accounts/profile/
X-API-Session-Cookie-Name: awx_sessionid
Expires: <date>
Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
Vary: Cookie, Accept-Language, Origin
Session-Timeout: 1800
Content-Language: en
X-API-Total-Time: 0.377s
X-API-Request-Id: 700826696425433fb0c8807cd40c00a0
Access-Control-Expose-Headers: X-API-Request-Id
Set-Cookie: userLoggedIn=true; Path=/
Set-Cookie: current_user=<user cookie data>; Path=/
Set-Cookie: csrftoken=<csrftoken>; Path=/; SameSite=Lax
Set-Cookie: awx_sessionid=<your session id>; expires=<date>; HttpOnly; Max-Age=1800; Path=/; SameSite=Lax
Strict-Transport-Security: max-age=15768000

Server: nginx
Date: <current date>
Content-Type: text/html; charset=utf-8
Content-Length: 0
Connection: keep-alive
Location: /accounts/profile/
X-API-Session-Cookie-Name: awx_sessionid
Expires: <date>
Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
Vary: Cookie, Accept-Language, Origin
Session-Timeout: 1800
Content-Language: en
X-API-Total-Time: 0.377s
X-API-Request-Id: 700826696425433fb0c8807cd40c00a0
Access-Control-Expose-Headers: X-API-Request-Id
Set-Cookie: userLoggedIn=true; Path=/
Set-Cookie: current_user=<user cookie data>; Path=/
Set-Cookie: csrftoken=<csrftoken>; Path=/; SameSite=Lax
Set-Cookie: awx_sessionid=<your session id>; expires=<date>; HttpOnly; Max-Age=1800; Path=/; SameSite=Lax
Strict-Transport-Security: max-age=15768000

+ 사용자가 이 방법으로 성공적으로 인증되면 서버는 세션 쿠키의 구성된 이름을 나타내는 X-API-Session-Cookie-Name 이라는 헤더로 응답합니다. 기본값은 awx_session_id 이며 나중에 Set-Cookie 헤더에서 볼 수 있습니다.

+

기본 인증은 상태 비저장이므로 base64로 인코딩된 사용자 이름과 암호를 인증 헤더를 통해 각 요청과 함께 보내야 합니다. curl 요청, python 스크립트 또는 API에 대한 개별 요청의 API 호출에 이 값을 사용할 수 있습니다.

가능한 경우 API에 액세스하려면 OAuth 2 토큰 인증을 권장합니다.

다음은 curl을 사용한 기본 인증의 예입니다.

the --user flag adds this Authorization header for us

# the --user flag adds this Authorization header for us
curl -X GET --user 'user:password' https://<controller-host>/api/gateway/v1/tokens/ -k -L

OAuth(Open Authorization)는 토큰 기반 인증 및 권한 부여를 위한 오픈 표준입니다. OAuth 2 인증은 일반적으로 자동화 컨트롤러 API와 프로그래밍 방식으로 상호 작용할 때 사용됩니다.

기본 인증과 유사하게 인증 헤더를 통해 각 API 요청과 함께 OAuth 2 토큰이 제공됩니다. 기본 인증과 달리 OAuth 2 토큰에는 구성 가능한 타임아웃이 있으며 범위를 지정할 수 있습니다. 토큰은 구성 가능한 만료 시간이 있으며 한 사용자 또는 필요한 경우 관리자가 전체 자동화 컨트롤러 시스템에 대해 쉽게 취소할 수 있습니다. cancel _oauth2_tokens 관리 명령을 사용하거나 액세스 토큰 Revoke 에 설명된 대로 API를 사용하여 이 작업을 수행할 수 있습니다.

자동화 컨트롤러에서 OAuth2 액세스 토큰을 가져오는 다양한 방법은 다음과 같습니다.

사용자는 API 또는 플랫폼 게이트웨이 UI의 Access Management → OAuth 애플리케이션 탭에서 OAuth 2 토큰을 생성해야 합니다. UI를 통해 토큰 생성에 대한 자세한 내용은 토큰 추가 를 참조하십시오.

이 예제의 목적을 위해 PAT 방법을 사용하여 API에서 토큰을 생성합니다. 생성한 후 범위를 설정할 수 있습니다.

토큰 인증은 Python 스크립트 또는 curl과 같은 자동화 컨트롤러 API의 프로그래밍 방식으로 사용하는 데 가장 적합합니다.

curl 예

curl -u user:password -k -X POST https://<platform-host>/api/gateway/v1/tokens/

curl -u user:password -k -X POST https://<platform-host>/api/gateway/v1/tokens/

이 호출은 다음을 사용하여 JSON 데이터를 반환합니다.

View larger image

token 속성 값을 사용하여 Hosts와 같은 자동화 컨트롤러 리소스에 대한 GET 요청을 수행할 수 있습니다.

curl -k -X GET \
  -H “Content-Type: application/json”
  -H “Authorization: Bearer <oauth2-token-value>” \
  https://<platform-host>/api/controller/v2/hosts/

curl -k -X GET \
  -H “Content-Type: application/json”
  -H “Authorization: Bearer <oauth2-token-value>” \
  https://<platform-host>/api/controller/v2/hosts/

시작하려는 작업 템플릿에 대한 POST 를 수행하여 작업을 실행할 수도 있습니다.

curl -k -X POST \
  -H "Authorization: Bearer <oauth2-token-value>" \
  -H "Content-Type: application/json" \
  --data '{"limit" : "ansible"}' \
  https://<platform-host>/api/controller/v2/job_templates/14/launch/

curl -k -X POST \
  -H "Authorization: Bearer <oauth2-token-value>" \
  -H "Content-Type: application/json" \
  --data '{"limit" : "ansible"}' \
  https://<platform-host>/api/controller/v2/job_templates/14/launch/

SSO(Single Sign-On) 인증 방법은 사용자 인증이 Google SSO, Microsoft Azure SSO, SAML 또는 GitHub와 같은 자동화 컨트롤러 외부에 수행되므로 다른 방법과 다릅니다.

중앙 ID 공급자가 있는 대규모 조직 내에서 자동화 컨트롤러를 사용하여 SSO 인증을 구성할 수 있습니다. 자동화 컨트롤러에서 SSO 메서드를 구성한 후에는 로그인 화면에서 해당 SSO에 대한 옵션을 사용할 수 있습니다. 해당 옵션을 클릭하면 ID 공급자(이 경우 GitHub)로 리디렉션됩니다. 이 경우 인증 정보가 제공됩니다. ID 공급자가 사용자를 성공적으로 확인하면 자동화 컨트롤러에서 GitHub 사용자에게 연결된 사용자를 만들고(이 SSO 방법을 사용하여 처음 로그인하는 경우) 로그인합니다.