ユーザーリストの API エンドポイント¶

このリソースに GET リクエストを実行して、ユーザーリストを取得します。

GET /api/v2/users/
HTTP 200 OK
Allow: GET, POST, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept
X-API-Node: localhost
X-API-Time: 0.097s


{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "type": "user",
            "url": "/api/v2/users/1/",
            "related": {
                "admin_of_organizations": "/api/v2/users/1/admin_of_organizations/",
                "organizations": "/api/v2/users/1/organizations/",
                "roles": "/api/v2/users/1/roles/",
                "access_list": "/api/v2/users/1/access_list/",
                "teams": "/api/v2/users/1/teams/",
                "credentials": "/api/v2/users/1/credentials/",
                "activity_stream": "/api/v2/users/1/activity_stream/",
                "projects": "/api/v2/users/1/projects/"
            },
            "summary_fields": {
                "user_capabilities": {
                    "edit": true,
                    "delete": false
                }
            },
            "created": "2017-09-06T02:55:30.492Z",
            "username": "admin",
            "first_name": "",
            "last_name": "",
            "email": "[email protected]",
            "is_superuser": true,
            "is_system_auditor": false,
            "ldap_dn": "",
            "external_account": null,
            "auth": []
        }
    ]
}

返されるデータ構造には以下のものが含まれます。

{
    "count": 99,
    "next": null,
    "previous": null,
    "results": [
        ...
    ]
}

count フィールドはクエリーで見つかったユーザーの合計数を示します。next および previous フィールドは、単一ページに収まらない結果がある場合に、それらの結果へのリンクを提供します。results にはユーザーのレコードが一覧表示されますが、ゼロの場合もあります。

結果¶

各ユーザーのデータ構造には以下のフィールドが含まれます。

id: ユーザーのデータベース ID (整数)
type: ユーザーのデータタイプ (複数選択)
url: ユーザーの URL (文字列)
related: 関連リソースの URL のあるデータ構造 (オブジェクト)
summary_fields: 関連リソースの名前/説明のあるデータ構造 (オブジェクト)
created: ユーザー作成時のタイムスタンプ (日時)
username: 必須。30 文字以下で、英数字および @/./+/-/_ の文字が使用可能 (文字列)
first_name: (文字列)
last_name: (文字列)
email: (email)
is_superuser: 明示的にパーミッションを割り当てることなく、このユーザーに全パーミッションがあることを指定します (ブール値)
is_system_auditor: (ブール値)
ldap_dn: (文字列)
external_account: アカウントが外部サービスで管理される場合に設定されます (フィールド)

並び替え¶

特定の順番でユーザーが返されることを指定するには、order_by クエリー文字列のパラメーターを GET リクエストで使用します。

?order_by=name

逆の順序に並び替えるには、フィールド名の前にダッシュ - を加えます。

?order_by=-name

フィールド名をコンマ , 区切りにすると、複数のフィールドの並び替えを指定できます。

?order_by=name,some_other_field

ページネーション¶

各リクエストで返される結果数を変更するには、page_size クエリー文字列パラメーターを使用します。特定のページの結果を取得するには、page クエリー文字列パラメーターを使用します。

?page_size=100&amp;page=2

結果で返される previous および next のリンクは、これらのクエリー文字列パラメーターを自動的に設定します。

検索¶

モデルの指定された全テキストフィールド内で大文字小文字の区別のない検索を実行するには、search クエリー文字列のパラメーターを使用します。

?search=findme

関連フィールドを検索します (AWX 1.4 / Ansible Tower 3.1 で追加)。

?related__search=findme

フィルタリング¶

特定の値に一致する結果一覧に対して、追加のクエリー文字列パラメーターを使ってフィルタリングすることもできます。このフィルタリングに使用できるのは、データベースに存在するフィールドと関係のみです。指定された値の特殊文字は、エンコードされた URL にする必要があります。例を示します。

?field=value%20xyz

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

?other__field=value

特定の基準に一致する結果を除外するには、フィールドパラメーターの前に not__ を追加します。

?not__field=value

デフォルトでは、クエリー文字列フィルターはすべて AND 条件になっているので、すべての フィルターに一致する結果のみが返されます (AWX 1.4 で追加)。複数基準の いずれか に一致する結果にまとめるには、各クエリー文字列パラメーターの前に or__ を追加します。

?or__field=value&amp;or__field=othervalue
?or__not__field=value&amp;or__field=othervalue

デフォルトの AND 条件のフィルタリングでは、データベース関係全体でフィルタリングされている関連オブジェクトそれぞれに同時に全フィルターが適用されます (Ansible Tower 1.4.5 で追加) 。チェーンフィルター (chain) では、フィルターを個別に関連オブジェクトごとに適用します。これを使用するには、chain__ をクエリー文字列パラメーターの前に追加します。

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

上記で最初のクエリーが ?related__field=value&related__field2=othervalue となっていれば、同一の関連オブジェクトが両方の条件を満たしているプライマリーオブジェクトのみが返されますが、上記通りのチェーンフィルターを使用すると、各条件に一致するプライマリーオブジェクトの共通集合が返されます。

フィールド名に lookup を追加すると、より詳細なクエリーによるフィールドルックアップが可能になります。

?field__lookup=value

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

exact: 完全一致 (指定されない場合のデフォルトのルックアップ)
iexact: 大文字小文字の区別のない exact
contains: フィールドに値を含む
icontains: 大文字小文字の区別のない contains
startswith: 値で始まるフィールド
istartswith: 大文字小文字の区別のない startswith
endswith: 値で終わるフィールド
iendswith: 大文字小文字の区別のない endswith
regex: 特定の正規表現に一致するフィールド
iregex: 大文字小文字の区別のない regex
gt: Greater than の比較条件
gte: Greater than or equal to の比較条件
lt: Less than の比較条件
lte: Less than or equal to の比較条件
isnull: 特定フィールドもしくは関連オブジェクトが null かどうかをチェック。ブール値を想定
in: 特定フィールドの値が提供されたリストに存在するかどうかをチェック。アイテムのリストを想定

ブール値は true の場合 True または 1 を、false の場合は False または 0 を指定します (どちらも大文字小文字の区別なし)。

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

in ルックアップのリストは、値をコンマ区切りのリストとして指定することができます。

クエリー文字列のパラメーターによるユーザーのアクセスレベルのリクエストをベースにしたフィルタリング (Ansible Tower 3.1 で追加)。

role_level: フィルターをかけるロールのレベル。例、admin_role

ユーザーの作成¶

新規ユーザーを作成するには、以下のユーザーフィールドを使ってリソースに POST リクエストを実行します。

username: 必須。30 文字以下で、英数字および @/./+/-/_ の文字が使用可能 (文字列)
first_name: (文字列。デフォルトは "")
last_name: (文字列。デフォルトは "")
email: (email。デフォルトは "")
is_superuser: 明示的にパーミッションを割り当てることなく、このユーザーに全パーミッションがあることを指定します (ブール値。デフォルトは false)
is_system_auditor: (ブール値。デフォルトは false)
password: パスワード変更用の書き込み専用フィールド (文字列。デフォルトは "")

オプションエンドポイントの確認¶

オプションエンドポイント テーブルでは、このエンドポイントのオプションを確認できます。ブラウザー表示が可能な API でエンドポイントを表示している場合は、「オプション」ボタンをクリックすると以下の raw JSON が表示されます。

name

User List

description

# List Users: Make a GET request to this resource to retrieve the list of users.

renders

0	application/json
1	text/html

parses

0	application/json

added_in_version

1.2

actions

POST

username

type	string
required	true
label	Username
help_text	Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ only.
max_length	30

first_name

type	string
required	false
label	First name
max_length	30

last_name

type	string
required	false
label	Last name
max_length	30

email

type	string
required	false
label	Email address
max_length	254

is_superuser

type	boolean
required	false
label	Superuser status
help_text	Designates that this user has all permissions without explicitly assigning them.
default	false

is_system_auditor

type	boolean
required	false
label	Is system auditor
default	false

password

type	string
required	false
label	Password
help_text	Write-only field used to change the password.
default	(Empty Text)
write_only	true

GET

id

type	integer
label	ID
help_text	Database ID for this user.

type

choice

help_text

Data type for this user.

choices

0

0	user
1	User

url

type	string
label	URL
help_text	URL for this user.

type	object
label	Related
help_text	Data structure with URLs of related resources.

summary_fields

type	object
label	Summary fields
help_text	Data structure with name/description for related resources.

created

type	datetime
label	Created
help_text	Timestamp when this user was created.

username

type	string
label	Username
help_text	Required. 30 characters or fewer. Letters, numbers and @/./+/-/_ only.

first_name

type	string
label	First name

last_name

type	string
label	Last name

email

type	string
label	Email address

is_superuser

type	boolean
label	Superuser status
help_text	Designates that this user has all permissions without explicitly assigning them.

is_system_auditor

type	boolean
label	Is system auditor

ldap_dn

type	string
label	Ldap dn

external_account

type	field
label	External account
help_text	Set if the account is managed by an external service.

types

0	user

search_fields

0	username
1	first_name
2	last_name
3	email