8. 액세스 리소스¶

8.1. 구성 설정¶

``/api/v2/settings/named-url/``에는 이름이 지정된 URL 관련 구성 설정이 두 개 있습니다.

NAMED_URL_FORMATS 및 NAMED_URL_GRAPH_NODES

``NAMED_URL_FORMATS``는 이름이 지정된 모든 사용 가능한 URL ID 형식으로 이루어진 읽기 전용 키-값 쌍 목록입니다. 일반적인 ``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 이름이고, 값은 해당 리소스에 대해 사람이 읽을 수 있는 고유 ID를 형성하는 방법을 나타내는 문자열입니다. ``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``은 사람이 읽을 수 있는 고유 ID와 이름이 지정된 URL 자체를 구성할 만큼 충분히 유용합니다. 사용하기 쉽도록 이름이 지정된 URL을 포함할 수 있는 리소스의 모든 오브젝트에는 해당 오브젝트의 이름이 지정된 URL을 표시하는 관련 필드 ``named_url``이 있습니다. 사용자 정의 용도로 해당 필드를 복사하여 붙여넣을 수 있습니다. 또한 리소스 오브젝트에 추가 지침을 위한 이름이 지정된 URL이 있는 경우 API 브라우저의 도움말 텍스트를 참조하십시오.

ID가 5인 레이블의 이름이 지정된 URL을 수동으로 결정한다고 가정하겠습니다. ``NAMED_URL_FORMATS``를 사용하여 이 특정 리소스 오브젝트에 대해 이름이 지정된 URL을 구성하는 일반적인 절차는 먼저 ``NAMED_URL_FORMATS``의 레이블 필드를 찾아 ID 형식 ``<name>++<organization.name>``을 가져오는 것입니다.

• URL 형식의 첫 번째 부분은 <name>``이며, 이는 레이블 리소스 세부 정보가 ``/api/v2/labels/5/``에 있고 반환된 JSON에서 ``name 필드를 찾을 수 있음을 나타냅니다. 값이 〈Foo’인 name 필드가 있다고 가정하면 고유 ID의 첫 번째 부분은 **Foo**가 됩니다.

• 형식의 두 번째 부분은 이중 더하기 기호(++)입니다. 이 기호는 고유 ID의 다양한 부분을 구분합니다. **Foo++**를 가져오려면 고유 ID에 추가합니다.

• 형식의 세 번째 부분은 <organization.name>``이며, 이는 해당 필드가 조사 중인 현재 레이블 오브젝트에 있지 않고 레이블 오브젝트가 가리키는 조직에 있음을 나타냅니다. 따라서 형식이 표시되면 현재 반환된 JSON의 관련 필드에서 조직을 찾습니다. 해당 필드가 존재하거나 존재하지 않을 수 있습니다. 존재하는 경우 해당 필드에 지정된 URL(예: ``/api/v2/organizations/3/)을 따라 특정 조직의 세부 정보를 가져와서 name 필드(예: ‘기본값’)를 추출한 후 현재의 고유 ID에 추가합니다. ``<organizations.name>``은 형식의 마지막 부분이므로 결과적으로 생성되는 이름이 지정된 URL은 ``/api/v2/labels/Foo++Default/``입니다. 레이블 오브젝트 세부 정보의 관련 필드에 조직이 없는 경우에는 대신 빈 문자열을 추가합니다. 빈 문자열은 기본적으로 현재 ID를 변경하지 않습니다. 따라서 ``Foo++``가 최종 고유 ID가 되고, 결과적으로 생성되는 이름이 지정된 URL은 ``/api/v2/labels/Foo++/``입니다.

이름이 지정된 URL에 대한 고유 ID를 생성하는 작업의 중요한 측면은 예약된 문자와 관련이 있습니다. ID는 URL의 일부이므로 URL 표준에 의해 예약된 ;/?:@=&[] 문자는 퍼센트 기호로 인코딩됩니다. 예를 들어, 조직 이름이 ;/?:@=&[]``인 경우 고유 ID는 ``%3B%2F%3F%3A%40%3D%26%5B%5D``입니다. 또 다른 특수 예약 문자는 ``+``로, URL 표준에 의해 예약되지는 않았지만 이름이 지정된 URL에서 ID의 다른 부분을 연결하는 데 사용합니다. 이 문자는 ``[+]``로 인코딩됩니다. 예를 들어, 조직 이름이 ``[+]``인 경우 고유 ID는 ``%5B[+]%5D``입니다. 여기서 원래의 ``[ 및 ``]``는 퍼센트 기호로 인코딩되고 ``+``는 ``[+]``로 변환됩니다.

``NAMED_URL_FORMATS``는 수동으로 수정할 수 없지만 기본 리소스 수정 및 확장을 반영하여 시간이 지남에 따라 수정이 자동으로 수행되고 확장됩니다. 이름이 지정된 URL 기능을 사용할 해당 클러스터의 ``NAMED_URL_FORMATS``를 참조하십시오.

``NAMED_URL_GRAPH_NODES``는 이름이 지정된 URL을 관리하는 데 사용되는 내부 그래프 데이터 구조를 노출하는 또 다른 읽기 전용 키-값 쌍 목록입니다. 이 목록은 사람이 읽을 수 있도록 고안된 것은 아니지만 이름이 지정된 URL을 프로그래밍 방식으로 생성하는 데 사용해야 합니다. 이름이 지정된 URL을 포함할 수 있는 임의의 리소스 오브젝트 기본 키를 제공하고 ``NAMED_URL_GRAPH_NODES``에서 제공하는 정보를 사용하여 이름이 지정된 URL을 생성하는 스크립트의 예는 GitHub(https://github.com/ansible/awx/blob/devel/tools/scripts/pk_to_named_url.py.)에서 확인할 수 있습니다.

8.2. ID 형식 프로토콜¶

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

1. 키에는 name 필드인 필드만 포함하거나 가능한 선택 항목이 제한된 텍스트 필드(예: 인증 정보 유형 리소스의 kind 필드)만 포함되어야 합니다.

2. 1번 규칙을 위반하며 유일하게 허용되는 예외적인 필드는 해당 리소스 이외의 리소스와 관련된 다대일 관련 필드입니다. 이러한 리소스에는 슬러그도 포함될 수 있습니다.

리소스 Foo 및 Bar``가 있고 ``Foo``와 ``Bar 둘 다 〈yes〉 또는 〈no〉 값만 포함할 수 있는 name 필드와 choice 필드가 있다고 가정하겠습니다. 또한 리소스 Foo``에는 ``Bar``와 관련된 다대일 필드(외래 키)가 포함되어 있습니다(예: ``fk). Foo``의 고유 키 튜플은 ``name, choice, fk``이고, ``Bar``의 고유 키 튜플은 ``name, choice``입니다. ``Bar``는 위의 1번 규칙을 충족하기 때문에 이름이 지정된 URL을 포함할 수 있습니다. ``Foo``는 1번 규칙을 위반하더라도 이름이 지정된 URL을 포함할 수 있습니다. 1번 규칙을 위반하는 추가 필드는 ``Bar``와 관련된 다대일 ``fk 필드이며, ``Bar``는 이름이 지정된 URL을 포함할 수 있습니다.

위의 1번 규칙을 충족하는 리소스의 경우 사람이 읽을 수 있는 고유 ID는 +``로 구분된 외래 키 필드의 조합입니다. 특히 위 예에서 리소스 ``Bar``는 슬러그 형식 ``<name>+<choice>``를 취합니다. 슬러그 형식에서는 필드 순서가 중요합니다. ``name 필드가 있는 경우 항상 먼저 오고 나머지 모든 필드가 필드 이름의 사전순으로 정렬되어 그 뒤에 이어집니다. 예를 들어, Bar에도 1번 규칙을 충족하는 a_choice 필드가 있어 고유 키가 name, choice, ``a_choice``가 되는 경우 슬러그 형식은 ``<name>+<a_choice>+<choice>``입니다.

위의 2번 규칙을 충족하는 리소스의 경우 추가 외래 키 필드를 통해 역추적하면 결과는 해당 리소스의 오브젝트를 모두 함께 식별하는 리소스 트리입니다. ID 형식을 생성하기 위해 역추적 트리의 각 리소스는 외래 키를 제외한 모든 필드를 사용하여 이전에 설명한 방식으로 독립 형식의 고유한 부분을 생성합니다. 마지막으로 모든 부분은 ``++``에 의해 다음 순서대로 결합됩니다.

• 첫 번째 ID 구성 요소로 독립 형식을 배치합니다.

• 각 리소스에 대한 고유 ID를 재귀적으로 생성합니다. 기본 리소스는 외래 키(역추적 트리의 자식 노드) 사용을 나타냅니다.

• 생성된 고유 ID를 나머지 ID 구성 요소로 취급합니다. 이러한 ID는 해당 외래 키의 사전순으로 정렬합니다.

• ``++``를 사용하여 모든 구성 요소를 결합하여 최종 ID 형식을 생성합니다.

위 예에 대한 참조에서 리소스 Foo``의 ID 형식을 생성할 때 컨트롤러는 독립 형식(``Foo``의 경우 ``<name>+<choice>, <fk.name>+<fk.choice>``의 경우 ``Bar)을 생성한 다음 이를 ``<name>+<choice>++<fk.name>+<fk.choice>``로 결합합니다.

지정된 ID 형식에 따라 ID를 생성할 때 외래 키가 위치를 가리키지 않을 수도 있습니다. 이 경우 컨트롤러는 외래 키가 가리켜야 하는 리소스에 해당하는 형식 부분을 빈 문자열 〈〉로 대체합니다. 예를 들어, Foo 오브젝트에 name =〉alice〉, choice =〉yes’가 있지만 ``fk``에 field = None이 있는 경우 ID는 ``alice+yes++``가 됩니다.