Documentation

プロジェクトリストの API エンドポイント

このリソースに GET リクエストを実行して、プロジェクトリストを取得します。

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

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

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

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

結果

各プロジェクトデータ構造には以下のフィールドが含まれます。

  • id: プロジェクトのデータベース ID (整数)
  • type: プロジェクトのデータタイプ (選択)
    • project: プロジェクト
  • url: プロジェクトの URL (文字列)
  • related: 関連リソースの URL のあるデータ構造 (オブジェクト)
  • summary_fields: 関連リソースの名前/説明のあるデータ構造 (オブジェクト)
  • created: プロジェクト作成時のタイムスタンプ (日時)
  • modified: プロジェクトの最終更新時のタイムスタンプ (日時)
  • name: プロジェクトの名前 (文字列)
  • description: プロジェクトのオプションでの説明 (文字列)
  • local_path: このプロジェクトの Playbook および関連するファイルを含むローカルパス (PROJECTS_ROOT との相対) (文字列)
  • scm_type: プロジェクトを保存するために使用されるソースコントロールシステムを指定します (選択)
    • "": 手動
    • git: Git
    • hg: Mercurial
    • svn: Subversion
    • insights: Red Hat Insights
  • scm_url: プロジェクトが保存される場所 (文字列)
  • scm_branch: チェックアウトする特定のブランチ、タグまたはコミット (文字列)
  • scm_clean: ローカル変更を破棄してからプロジェクトを同期します (ブール値)
  • scm_delete_on_update: プロジェクトを削除してから同期します (ブール値)
  • credential: (フィールド)
  • timeout: タスクが取り消されるまでの秒単位での実行時間 (整数)
  • last_job_run: (日時)
  • last_job_failed: (ブール値)
  • next_job_run: (日時)
  • status: (選択)
    • new: 新規
    • pending: 保留中
    • waiting: 待機中
    • running: 実行中
    • successful: 成功
    • failed: 失敗
    • error: エラー
    • canceled: キャンセル済み
    • never updated: 更新されていません
    • ok: OK
    • missing: 不明
  • organization: (フィールド)
  • scm_delete_on_next_update: (ブール値)
  • scm_update_on_launch: プロジェクトを使用するジョブの起動時にプロジェクトを更新します (ブール値)
  • scm_update_cache_timeout: 新規プロジェクトの更新がジョブの依存関係として起動される最終プロジェクト更新後の秒数 (整数)
  • scm_revision: プロジェクト更新で取得される最新リビジョン (文字列)
  • last_update_failed: (ブール値)
  • last_updated: (日時)

並び替え

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

?order_by=name

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

?order_by=-name

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

?order_by=name,some_other_field

検索

モデルの指定された全テキストフィールド内で大文字小文字の区別のない検索を実行するには、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&or__field=othervalue
?or__not__field=value&or__field=othervalue

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

?chain__related__field=value&chain__related__field2=othervalue
?chain__not__related__field=value&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 リクエストを実行します。

  • name: (文字列。必須)
  • description: (文字列。デフォルトは "")
  • local_path: このプロジェクトの Playbook および関連するファイルを含むローカルパス (PROJECTS_ROOT との相対) (文字列。デフォルトは "")
  • scm_type: (選択)
    • "": 手動 (デフォルト)
    • git: Git
    • hg: Mercurial
    • svn: Subversion
  • scm_url: (文字列。デフォルトは "")
  • scm_branch: チェックアウトする特定のブランチ、タグまたはコミット (文字列。デフォルトは "")
  • scm_clean: (ブール値。デフォルトは False)
  • scm_delete_on_update: (ブール値。デフォルトは False)
  • credential: (フィールド。デフォルトは None)
  • timeout: タスクが取り消されるまでの秒単位での実行時間 (整数。デフォルトは 0)
  • organization: (フィールド)
  • scm_update_on_launch: (ブール値。デフォルトは False)
  • scm_update_cache_timeout: (整数。デフォルトは 0)

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

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

name Project List
description # List Projects: Make a GET request to this resource to retrieve the list of projects.
renders
0 application/json
1 text/html
parses
0 application/json
added_in_version 1.2
actions
POST
name
type string
required
true
label Name
max_length 512
help_text Name of this project.
description
type string
required
false
label Description
help_text Optional description of this project.
default (Empty Text)
local_path
type string
required
false
label Local path
help_text Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project.
max_length 1024
scm_type
type choice
required
false
label SCM Type
help_text Specifies the source control system used to store the project.
default (Empty Text)
choices
0
0 (Empty Text)
1 Manual
1
0 git
1 Git
2
0 hg
1 Mercurial
3
0 svn
1 Subversion
4
0 insights
1 Red Hat Insights
scm_url
type string
required
false
label SCM URL
help_text The location where the project is stored.
max_length 1024
default (Empty Text)
scm_branch
type string
required
false
label SCM Branch
help_text Specific branch, tag or commit to checkout.
max_length 256
default (Empty Text)
scm_clean
type boolean
required
false
label Scm clean
help_text Discard any local changes before syncing the project.
default
false
scm_delete_on_update
type boolean
required
false
label Scm delete on update
help_text Delete the project before syncing.
default
false
credential
type field
required
false
label Credential
timeout
type integer
required
false
label Timeout
help_text The amount of time (in seconds) to run before the task is canceled.
min_value
-2147483648
max_value
2147483647
default
0
organization
type field
required
false
label Organization
scm_update_on_launch
type boolean
required
false
label Scm update on launch
help_text Update the project when a job is launched that uses the project.
default
false
scm_update_cache_timeout
type integer
required
false
label Scm update cache timeout
help_text The number of seconds after the last project update ran that a new project update will be launched as a job dependency.
min_value
0
max_value
2147483647
default 0
GET
id
type integer
label ID
help_text Database ID for this project.
type
type choice
label Type
help_text Data type for this project.
choices
0
0 project
1 Project
url
type string
label Url
help_text URL for this project.
related
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 project was created.
modified
type datetime
label Modified
help_text Timestamp when this project was last modified.
name
type string
label Name
help_text Name of this project.
description
type string
label Description
help_text Optional description of this project.
local_path
type string
label Local path
help_text Local path (relative to PROJECTS_ROOT) containing playbooks and related files for this project.
scm_type
type choice
label SCM Type
choices
0
0 (Empty Text)
1 Manual
1
0 git
1 Git
2
0 hg
1 Mercurial
3
0 svn
1 Subversion
4
0 insights
1 Red Hat Insights
scm_url
type string
label SCM URL
help_text The location where the project is stored.
scm_branch
type string
label SCM Branch
help_text Specific branch, tag or commit to checkout.
scm_clean
type boolean
label Scm clean
help_text Discard any local changes before syncing the project.
scm_delete_on_update
type boolean
label Scm delete on update
help_text Delete the project before syncing.
credential
type field
label Credential
timeout
type integer
label Timeout
help_text The amount of time (in seconds) to run before the task is canceled.
min_value
-2147483648
max_value
2147483647
last_job_run
type datetime
label Last job run
last_job_failed
type boolean
label Last job failed
next_job_run
type datetime
label Next job run
status
type choice
label Status
choices
0
0 new
1 New
1
0 pending
1 Pending
2
0 waiting
1 Waiting
3
0 running
1 Running
4
0 successful
1 Successful
5
0 failed
1 Failed
6
0 error
1 Error
7
0 canceled
1 Canceled
8
0 never updated
1 Never Updated
9
0 ok
1 OK
10
0 missing
1 Missing
organization
type field
label Organization
scm_delete_on_next_update
type boolean
label Scm delete on next update
scm_update_on_launch
type boolean
label Scm update on launch
help_text Update the project when a job is launched that uses the project.
scm_update_cache_timeout
type integer
label Scm update cache timeout
help_text The number of seconds after the last project update ran that a new project update will be launched as a job dependency.
min_value
0
max_value
2147483647
scm_revision
type string
label SCM Revision
help_text The last revision fetched by a project update.
last_update_failed
type boolean
label Last update failed
last_updated
type datetime
label Last updated
types
0 project
search_fields
0 description
1 name

Copyright © 2017 Red Hat, Inc.

Red Hat Ansible Tower docs are generated using Sphinx using a theme provided by Read the Docs.