8. リソースへのアクセス¶

8.1. 設定方法¶

/api/v2/settings/named-url/ 下には、2 つの名前付き URL 関連の設定があります。

NAMED_URL_FORMATS および NAMED_URL_GRAPH_NODES

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 内の各アイテムでは、名前付き 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 を持つことが可能なリソースのオブジェクトには関連フィールドである named_url があり、これはそのオブジェクトの名前付き URL を表示します。このフィールドをコピーして貼り付けることで、カスタム使用することが可能です。リソースオブジェクトに名前付き URL がある場合は、詳細について API ブラウザーのヘルプテキストを参照することもできます。

ID 5 のラベルについて、名前付き URL を手動で決定するとします。その場合、NAMED_URL_FORMATS を使用してこのリソースオブジェクトの名前付き URL を構成するには、NAMED_URL_FORMATS のラベルフィールドで、<name>++<organization.name> の識別子フォーマットを確認します。

• URL フォーマットの最初の部分は <name> で、これはラベルリソースの詳細が /api/v2/labels/5/ にあることを示し、返された JSON で name フィールドを確認します。name フィールドの値が 'Foo' だったとすると、一意の識別子の最初の部分は Foo となります。

• フォーマットの 2 番目の部分は、プラス記号 2 つである ++ となります。これは識別子の個別部分を分ける区切り記号です。これを識別子に追記して Foo++ とします。

• フォーマットの 3 番目の部分は <organization.name> で、これはフィールドは現在調べているラベルオブジェクトにはないものの、ラベルオブジェクトが指す組織内にあることを示します。つまり、フォーマットが示すように、現在返されている JSON 内の関連フィールドで組織を検索します。このフィールドは、ある場合とない場合があります。存在する場合は、そのフィールドにある URL、たとえば /api/v2/organizations/3/ に従い、特定の組織の詳細を取得し、 'Default' というようなその name フィールドを抽出して、それを現行の一意の識別子に加えます。<organizations.name> はフォーマットの最後の部分であることから、生成される名前付き URL は /api/v2/labels/Foo++Default/ となります。ラベルオブジェクト詳細の関連フィールドに組織が存在しない場合は、空の文字列を追記するので、実際には現行の識別子からは変更なしになります。このため、Foo++ が最後の一意の識別子となり、生成される名前付き URL は、/api/v2/labels/Foo++/ となります。

名前付き URL の一意の識別子生成における重要な側面の 1 つは予約文字です。識別子は 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 (https://github.com/ansible/awx/blob/devel/tools/scripts/pk_to_named_url.py) で参照できます。

8.2. 識別子フォーマットのプロトコル¶

リソースは、基本的にはリソースフィールドのタプルであるそれらの一意のキーで特定することができます。各リソースには一意のキーとしてのプライマリーキー番号が必ずありますが、他の複数の一意のキーが存在する場合もあります。リソースは識別子フォーマットを生成することが可能で、以下のルールのいずれかを満たす一意のキーが少なくとも 1 つある場合は、名前付き URL を持つことができます。

1. キーには、name フィールド、または (認証タイプリソースの kind フィールドのように) 有限数の選択肢のあるテキストフィールドのいずれかのみが含まれること。

2. 上記のルール 1 の唯一の例外フィールドは、リソース自体以外に関連する多対 1 の関連フィールドで、これはスラグを持つことが可能です。

Foo と Bar のリソースがあり、その Foo と Bar の両方に name フィールドと choice フィールドが含まれるとします。これらのフィールドの値には「yes」または「no」のいずれかのみ指定できます。また、リソース Foo には、fk のような Bar に関連する多対一のフィールド (外部キー) が含まれます。Foo には一意のキータプル (name、choice、fk) があり、Bar には一意のキータプル (name、choice) があります。Bar は上記のルール 1 を満たしているため、名前付き URL を指定できます。Foo はルール 1 を満たしていませんが、名前付き URL を指定できます。ルール 1 を違反している余分なフィールドは fk フィールドで、これが Bar に関連する多対一であり、Bar に名前付き URL を指定できるためです。

上記のルール 1 の条件を満たしているリソースの場合、人間が判読可能な一意の識別子は、+ で区切られた外部キーフィールドの組み合わせになります。上記のリソース Bar の場合は、スラグフォーマット <name>+<choice> になります。スラグフォーマットでは、フィールドの順番が重要であることに注意してください。name フィールドがある場合はこれが常に最初にきて、他のフィールド名が辞書的順序で続きます。たとえば、Bar にルール 1 を満たす a_choice フィールドもあり、一意のキーが (name、choice、a_choice) になったとすると、スラグフォーマットは <name>+<a_choice>+<choice> となります。

上記のルール 2 を満たすリソースの場合、新たな外部キーのフィールド経由でトレースバックした場合、結果はそのリソースのオブジェクトを一緒になって特定するリソースのツリーになります。識別子フォーマットを生成するために、トレースバックツリー内の各リソースは、外部キーを除くすべてのフィールドを使って、上記で説明した方法で自分の部分のスタンドアロンフォーマットを生成します。そして最後にすべての部分が以下の順番で ++ を使って結合されます。

• 識別子の最初のコンポーネントとしてスタンドアロンフォーマットが置かれます。

• 各リソースの一意の識別子が再帰的に生成されます。基礎となるリソースは、外部キー (トレースバックツリーノードの子) の使用を指します。

• 生成された一意の識別子は、残りの識別子コンポーネントとして扱われます。対応する外部キーの辞書的順序で並び替えられます。

• ++ で全コンポーネントを結合し、最終的な識別子フォーマットを生成します。

上記の例では、リソース Foo の識別子フォーマットを生成する際に、コントローラーは Foo には <name>+<choice>、Bar には <fk.name>+<fk.choice> というスタンドアロンフォーマットを生成し、それらを結合して <name>+<choice>++<fk.name>+<fk.choice> とします。

指定した識別子フォーマットに従って識別子を生成する際には、外部キーが何も指さない場合があります。この場合、コントローラーは、外部キーが本来指定すべきリソースに対応しているフォーマットの部分を空の文字列 '' で代用します。たとえば、Foo オブジェクトに name = 'alice'、choice = 'yes' があるものの、fk field = None の場合、生成される識別子は alice+yes++ となります。