Automation Controller API の概要

返される結果のリストを、指定された値に一致するアイテムだけに絞り込むために使用される追加のクエリー文字列パラメーターを使用できます。フィルタリングには、データベース内に存在するフィールドとリレーションのみを使用できます。指定された値の特殊文字が URL でエンコードされていることを確認します。以下に例を示します。

?field=value%20xyz

?field=value%20xyz

フィールドは関係にまで及ぶ可能性がありますが、その場合はデータベースで定義されたフィールドと関係に限定されます。

?other__field=value

?other__field=value

特定の基準に一致する結果を除外するには、フィールドパラメーターの前に 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 フィルタリングでは、データベースリレーションシップ全体でフィルタリングされる各関連オブジェクトにすべてのフィルターが同時に適用されます。チェーンフィルターは、代わりに関連するオブジェクトごとにフィルターを個別に適用します。これを使用するには、クエリー文字列パラメーターの前に 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

最初のクエリーを ?relatedfield=value&relatedfield2=othervalue と記述すると、同じ関連オブジェクトが両方の条件を満たしたプライマリーオブジェクトのみが返されます。チェーンフィルターを使用して記述すると、各条件に一致するプライマリーオブジェクトが交差している内容が返されます。

フィールド名にルックアップを追加することで、より高度なクエリーにフィールドルックアップを使用できます。

?field__lookup=value

?field__lookup=value

以下のフィールドのルックアップがサポートされています。

たとえば、?created__gte=2023-01-01 は、1/1/2023 以降で作成されたアイテムのリストを提供します。

null 値は None または Null (どちらも大文字と小文字は区別されません) として指定できますが、isnull ルックアップを使用して null 値を明示的にチェックすることを推奨します。

リスト (in ルックアップ用) を、コンマで区切られた値のリストとして指定できます。クエリー文字列のパラメーターによるユーザーのアクセスレベルの要求をもとにしたフィルタリング。

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

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

/api/v2/settings/named-url/: NAMED_URL_FORMATS および NAMED_URL_GRAPH_NODES という 2 つの名前付き 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 名です。値は、人間が判読できる、そのリソースの一意識別子を形成する方法を示す文字列です。NAMED_URL_FORMATS には、名前付き URL を持つことができるリソースのみがリストされ、そこにリストされていないリソースには名前付き URL はありません。リソースに名前付き URL を設定できる場合、そのオブジェクトには、オブジェクト固有の名前付き URL を表す named_url フィールドが必要です。このフィールドはリストビューではなく詳細ビューでのみ表示されます。正確に生成された名前付き URL を使用して、指定されたリソースオブジェクトにアクセスできます。これはオブジェクトとそれに関連する URL です。たとえば、/api/v2/res_name/obj_slug/ が有効な場合、/api/v2/res_name/obj_slug/related_res_name/ も有効です。

NAMED_URL_FORMATS は、人間が判読できる一意の識別子と名前付き URL 自体を作成するのに十分な情報を提供します。使いやすさを考慮して、名前付き URL を指定できるリソースのオブジェクトにはすべて、そのオブジェクトの名前付き URL を表示する関連フィールド named_url があります。そのフィールドをコピーして貼り付け、独自のカスタム用途に使用できます。詳細は、リソースオブジェクトに名前付き URL がある場合、API ブラウザーのヘルプテキストを参照してください。

名前付き URL ラベル (ID 5 など) を手動で決定できます。NAMED_URL_FORMATS を使用してこの特定のリソースオブジェクトの名前付き URL を作成するには、まず NAMED_URL_FORMATS の labels フィールドを参照して、識別子形式 <name>++<organization.name> を取得します。

名前付き URL の一意の識別子を生成する際の重要な側面は、予約文字に関係しています。識別子は URL の一部であるため、;/?:@=&[] などの、URL 標準による予約文字はパーセント記号でエンコードされます。たとえば、組織の名前が ;/?:@=&[] の場合、その一意の識別子は %3B%2F%3F%3A%40%3D%26%5B%5D になります。もう 1 つの特別な予約文字は + です。これは URL 標準では予約されていませんが、名前付き URL によって識別子のさまざまな部分をリンクするために使用されます。[+] でエンコードされます。たとえば、組織名が [+] の場合、その一意の識別子は %5B[+]%5D になります。ここで、元の [ と ] はパーセントにエンコードされ、+ は [+] に変換されます。

NAMED_URL_FORMATS は、手動で変更できませんが、変更は自動的に行われ、時間の経過とともに拡張され、基礎となるリソースの変更と拡張を反映します。名前付き URL 機能を使用する同じクラスターの NAMED_URL_FORMATS を参照してください。

NAMED_URL_GRAPH_NODES は、キーと値のペアのもう 1 つの読み取り専用リスト、名前付き URL を管理するために使用される内部グラフデータ構造を公開します。これは人間が読める形式ではありませんが、プログラムで名前付き URL を生成するために使用する必要があります。任意のリソースオブジェクトのプライマリーキーに NAMED_URL_GRAPH_NODES の情報を使用して、名前付きの URL を指定できる場合の、名前付き URL を生成するスクリプトのサンプルは、GitHub にあります。

リソースは、リソースフィールドのタプルである一意のキーによって識別できます。すべてのリソースには、一意のキーとしてプライマリーキー番号のみがあることが保証されていますが、他にも一意のキーが多数存在する場合があります。リソースは、次のルールを満たす一意のキーが少なくとも 1 つある場合に、識別子形式を生成し、名前付き URL を指定できます。

リソース Foo と Bar がある場合、Foo と Bar の両方に、名前フィールドと、値が "yes" または "no".のみになる選択フィールドが含まれます。さらに、リソース Foo には、Bar に関連する多対 1 フィールド (外部キー) (例: fk) があります。Foo には一意のキータプル (name、choice、fk) があり、Bar には一意のキータプル (name、choice) があります。Bar は、前述の最初のルールを満たしているため、名前付き URL を指定できます。Foo は、最初のルールに違反しているにもかかわらず、名前付き URL を指定できます。ルール 1 に違反する追加フィールドは、Bar と多対一の関係にある fk フィールドであり、Bar は 名前付き URL を指定できます。

ルール 1 を満たすリソースの場合、人間が判読できる一意の識別子は、+ で区切られた外部キーフィールドの組み合わせになります。具体的には、前述の例のリソース Bar のスラグ形式は <name>+<choice> です。スラグ形式ではフィールドの順序が重要であり、name フィールドが存在する場合は常に最初に表示され、その後に残りのフィールドがフィールド名の辞書順に配置されることに注意してください。たとえば、Bar にルール 1 を満たす a_choice フィールドもあり、一意のキーが name、choice、a_choice になる場合、そのスラグの形式は <name><a_choice><choice> になります。

ルール 2 を満たすリソースの場合、追加の外部キーフィールドを遡って追跡すると、その結果はそのリソースのオブジェクトを識別するリソースツリーになります。識別子形式を生成するために、トレースバックツリー内の各リソースは、外部キー以外のすべてのフィールドを使用して、スタンドアロン形式の独自の部分を生成します。最後に、すべての部分が次の順序で ++ で結合されます。

Foo リソースの識別子形式を生成する場合、Automation Controller がスタンドアロン形式 (Foo の場合は <name>+<choice>、Bar の場合は <fk.name>+<fk.choice>) を生成し、それらを結合して <name><choice>+<fk.name>+<fk.choice> にします。

指定された識別子形式に従って識別子を生成する場合、外部キーがどこも参照していない場合があります。この場合、Automation Controller は、外部キーが指すリソースに対応する形式の部分を空の文字列に置き換えます。たとえば、Foo オブジェクトが name ="alice"、choice ="yes"," であるが、fk field = None の場合、結果の識別子は alice+yes++ になります。

Automation Controller の API または UI に直接ログインするときにセッション認証を使用して、インベントリー、プロジェクト、ジョブテンプレートなどのリソースを手動で作成し、ブラウザーでジョブを開始できます。この方法を使用すると、その HTTP リクエストの間だけでなく、長時間ログインしたままにすることができます。たとえば、Chrome や Mozilla Firefox などのブラウザーで API または UI を参照する場合などです。ユーザーがログインすると、セッションクッキーが作成されます。つまり、Automation Controller 内の別のページに移動しても、ログインしたままにすることができます。次の図は、セッション中にクライアントとサーバーの間で行われる通信を表しています。

View larger image

curl ツールを使用して、Automation Controller にログインしたときに発生するアクティビティーを確認します。

これらはすべて、ブラウザーで UI または API にログインするときに Automation Controller によって実行され、ブラウザーで認証するときにのみ使用する必要があります。Automation Controller とのプログラムによる統合については、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 ヘッダーで確認できます。

Basic 認証はステートレスであるため、Authorization ヘッダーを介して各リクエストとともに、base64 でエンコードされたユーザー名とパスワードを送信する必要があります。これは、curl リクエスト、Python スクリプト、または API への個々のリクエストからの API 呼び出しに使用できます。可能な限り、API へのアクセスには OAuth 2 トークン認証を使用することを推奨します。

以下は、curl を使用した Basic 認証の例です。

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

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

Basic 認証の無効化

セキュリティー上の理由から、Basic 認証を無効にすることができます。

OAuth (Open Authorization) は、トークンベースの認証と承認のオープンスタンダードです。OAuth 2 認証は、Automation Controller API とプログラムでやり取りするときによく使用されます。Basic 認証と同様に、Authorization ヘッダーを通じて各 API リクエストに OAuth 2 トークンが付与されます。Basic 認証とは異なり、OAuth 2 トークンには設定可能なタイムアウトがあり、スコープ設定可能です。トークンには有効期限が設定されており、必要に応じて管理者が 1 ユーザーまたは Automation Controller システム全体に対して、トークンを簡単に取り消すことができます。これは、revoke_oauth2_tokens 管理コマンドを使用するか、アクセストークンの取り消し で説明されている API を使用して実行できます。

Automation Controller で OAuth2 アクセストークンを取得するためのさまざまな方法は次のとおりです。

ユーザーは、API または Automation Controller UI の Users > Tokens タブで OAuth 2 トークンを作成する必要があります。UI を介したトークンの作成に関する詳細は、Users - Tokens を参照してください。

この例では、API でトークンを作成するために PAT メソッドを使用します。作成後、スコープを設定できます。

トークン認証は、Python スクリプトや curl などのツールなど、Automation Controller API をプログラムで使用する場合に最適です。

curl -u user:password -k -X POST https://<controller-host>/api/v2/tokens/

curl -u user:password -k -X POST https://<controller-host>/api/v2/tokens/

この呼び出しは、次の JSON データを返します。

View larger image

token プロパティーの値を使用して、Hosts などの Automation Controller リソースに対して GET 要求を実行できます。

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

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

開始するジョブテンプレートに POST を実行してジョブを実行することもできます。

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

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

カスタムリクエストを記述する必要がある場合は、次の例のように、Python ライブラリーリクエストを使用して Python スクリプトを記述できます。

import requests
oauth2_token_value = 'y1Q8ye4hPvT61aQq63Da6N1C25jiA'   # your token value from controller
url = 'https://<controller-host>/api/v2/users/'
payload = {}
headers = {'Authorization': 'Bearer ' + oauth2_token_value,}

# makes request to controller user endpoint
response = requests.request('GET', url, headers=headers, data=payload,
allow_redirects=False, verify=False)

# prints json returned from controller with formatting
print(json.dumps(response.json(), indent=4, sort_keys=True))

import requests
oauth2_token_value = 'y1Q8ye4hPvT61aQq63Da6N1C25jiA'   # your token value from controller
url = 'https://<controller-host>/api/v2/users/'
payload = {}
headers = {'Authorization': 'Bearer ' + oauth2_token_value,}

# makes request to controller user endpoint
response = requests.request('GET', url, headers=headers, data=payload,
allow_redirects=False, verify=False)

# prints json returned from controller with formatting
print(json.dumps(response.json(), indent=4, sort_keys=True))

外部ユーザーが OAuth 2 トークンを作成できるようにする

デフォルトでは、シングルサインオンによって作成されたユーザーなどの外部ユーザーは、セキュリティー上の理由から OAuth トークンを生成できません。

シングルサインオン (SSO) 認証方法は、ユーザーの認証が Google SSO、Microsoft Azure SSO、SAML、GitHub などの Automation Controller の外部で行われるため、他の方法とは異なります。たとえば、GitHub SSO では、GitHub が唯一の真実のソースとなり、Automation Controller に指定したユーザー名とパスワードに基づいてアイデンティティーを検証します。

中央アイデンティティープロバイダーを備えた大規模な組織内で Automation Controller を使用して SSO 認証を設定できます。Automation Controller で SSO メソッドを設定すると、ログイン画面でその SSO のオプションが利用できるようになります。このオプションをクリックすると、アイデンティティープロバイダー (この場合は GitHub) にリダイレクトされ、そこで認証情報を提示します。アイデンティティープロバイダーで確認が済むと、Automation Controller は GitHub ユーザーにリンクされたユーザーを作成し (この SSO 方法で初めてログインする場合)、ログインします。