YouTrack および Hub ヘルプの開発者ポータル

Hub API フィールド構文

フィールド要求構文は、Google の部分的なリクエスト(英語)構文に基づいています。次のテキストは、GoogleAPI ドキュメントからの Hub API の引用に適用されます。

デフォルトでは、サーバーはリクエストの処理後にリソースのすべての即時フィールドを送り返します。ネストされたオブジェクトの場合、デフォルトでは基本情報（id など）のみが返されます。パフォーマンスを向上させるために、本当に必要なフィールドのみを返すようにサーバーに要求し、代わりに部分的な応答を取得することができます。

部分応答を要求するには、fields 要求パラメーターを使用して、返されるフィールドを指定します。このパラメーターは、応答データを返すすべての要求で使用できます。

サンプル

次の例は、サンプル API での fields パラメーターの使用を示しています。

簡単なリクエスト

簡単なリクエスト : この HTTP GET 要求は、fields パラメーターを省略し、完全なリソースを返します。

GET https://hub.project.com/api/rest/users/6b965961-846b-43b4-92be-2e40664ca81b

完全なリソース応答 : 完全なリソースデータには、簡潔にするために省略した他の多くのフィールドとともに、次のフィールドが含まれています。

{ "type": "user", "id": "6b965961-846b-43b4-92be-2e40664ca81b", "name": "Robin Taylor", "projectRoles": [ { "type": "projectRole", "id": "0173bba0-c99e-4189-b9a3-0bee2dbf2eb1", "role": { "id": "fbcd7c28-16d4-4531-925b-81fc7f35b1b9", "key": "system-admin", "name": "System Admin" }, "project": { "id": "0" }, "owner": { "type": "user", "id": "6b965961-846b-43b4-92be-2e40664ca81b", "login": "admin" } } ], "transitiveProjectRoles": [ { "type": "projectRole", "id": "47db71a0-aae1-47b3-97ca-e3e3a0e544e3", "role": { "id": "9c1cee56-e697-4c23-8f0f-73ac250ac1fc", "key": "observer", "name": "Observer" }, "project": { "id": "0" }, "owner": { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" } } ], "sourcedProjectRoles": [ { "type": "sourcedProjectRole", "id": "47db71a0-aae1-47b3-97ca-e3e3a0e544e3", "role": { "id": "9c1cee56-e697-4c23-8f0f-73ac250ac1fc", "key": "observer", "name": "Observer" }, "project": { "id": "0" }, "owner": { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" }, "sources": [ { "type": "groupProjectRoleSource", "group": { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" } } ] }, { "type": "sourcedProjectRole", "id": "0173bba0-c99e-4189-b9a3-0bee2dbf2eb1", "role": { "id": "fbcd7c28-16d4-4531-925b-81fc7f35b1b9", "key": "system-admin", "name": "System Admin" }, "project": { "id": "0" }, "owner": { "type": "user", "id": "6b965961-846b-43b4-92be-2e40664ca81b", "login": "admin" }, "sources": [ { "type": "ownRoleSource" } ] } ], "transitiveOrganizationRoles": [ { "type": "organizationRole", "id": "968c5d04-7afa-4397-b001-231a310abece", "role": { "id": "ed3b37a3-1f4c-4385-8e6d-5e2d37a8e91a", "key": "developer", "name": "Developer" }, "organization": { "id": "d706e386-da81-409d-b719-9245c1db681c" }, "owner": { "type": "userGroup", "id": "a2357529-c913-4ed5-9e1d-7464badfbd34" } } ], "sourcedOrganizationRoles": [ { "type": "sourcedOrganizationRole", "id": "968c5d04-7afa-4397-b001-231a310abece", "role": { "id": "ed3b37a3-1f4c-4385-8e6d-5e2d37a8e91a", "key": "developer", "name": "Developer" }, "organization": { "id": "d706e386-da81-409d-b719-9245c1db681c" }, "owner": { "type": "userGroup", "id": "a2357529-c913-4ed5-9e1d-7464badfbd34" }, "sources": [ { "type": "groupRoleSource", "group": { "type": "userGroup", "id": "a2357529-c913-4ed5-9e1d-7464badfbd34" } } ] } ], "login": "admin", "banned": false, "guest": false, "avatar": { "type": "urlavatar", "url": "https://hub.project.com/api/rest/avatar/6b965961-846b-43b4-92be-2e40664ca81b?etag=MjMtNDM%3D" }, "profile": { "avatar": { "type": "urlavatar", "url": "https://hub.project.com/api/rest/avatar/6b965961-846b-43b4-92be-2e40664ca81b?etag=MjMtNDM%3D" }, "email": { "type": "EmailJSON", "verified": false, "email": "robin.taylor@project.com" }, "locale": { "name": "en", "language": "en" } }, "groups": [ { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc" } ], "transitiveGroups": [ { "type": "userGroup", "id": "b5bfba7c-98cb-4b58-a52a-5fff0077a7a7" } ], "teams": [ { "type": "projectTeam", "id": "97d597c3-a48a-4961-83ab-2c39c3b579ef" } ], "transitiveTeams": [ { "type": "projectTeam", "id": "97d597c3-a48a-4961-83ab-2c39c3b579ef" } ], "details": [ { "type": "LoginuserdetailsJSON", "id": "a1aca5f7-ceb2-471a-906e-7a05c1ef35e6" } ], "VCSUserNames": [ { "name": "robin.taylor@project.com" } ], "creationTime": 1500362592707, "lastAccessTime": 1615297793582, "permanentTokens": [ { "id": "61-2" } ], "favoriteProjects": [ { "id": "d52e93b2-25fa-41c9-b0e1-c59b0edaac2e" } ], "endUserAgreementConsent": { "accepted": true, "majorVersion": 1, "minorVersion": 0, "time": 1519287697590, "address": "10.0.75.1" }, "requiredTwoFactorAuthentication": false, "pendingTwoFactorAuthentication": { "type": "TwoFactorAuthenticationSecretJSON" } }

部分的な応答の要求

部分的な応答の要求:

この同じリソースに対する次のリクエストでは、fields パラメーターを使用して、返されるデータの量と、ネストされたオブジェクトの詳細を取得するために必要なリクエストの数を大幅に削減します。

GET https://hub.project.com/api/rest/users/6109acd8-598b-44db-9e85-e99f3adca355?fields=name,banned,avatar/url,groups(id,name)

部分的な応答

上記の要求に応答して、サーバーは、名前付きユーザーグループのリストを含む基本的なユーザー情報のみを含む応答を送り返します。

{ "type": "user", "name": "Robin Taylor", "banned": false, "avatar": { "type": "urlavatar", "url": "https://hub.project.com/api/rest/avatar/6b965961-846b-43b4-92be-2e40664ca81b?etag=MjMtNDM%3D" }, "groups": [ { "type": "userGroup", "id": "abed5e54-203a-4551-9688-bbf27c82b5fc", "name": "Registered Users" }, { "type": "userGroup", "id": "fb70e9df-d97b-4350-a289-372e39ebba2a", "name": "Developers" }, { "type": "userGroup", "id": "97d597c3-a48a-4961-83ab-2c39c3b579ef_team", "name": "Team Tools Team" }, { "type": "userGroup", "id": "edf6bc5f-6b79-483b-8c35-5b8a78876e02_team", "name": "Academy Team" }, { "type": "userGroup", "id": "8a985f08-16af-4e5d-85d2-9cc26dbb14c1_team", "name": "edX Team" }, { "type": "userGroup", "id": "cc6e23ba-b963-4aeb-8869-a2eebc0a9d05_team", "name": "Customer Feedback Team" } ] }

応答は、選択したフィールドとそれを囲む親オブジェクトのみを含む JSON オブジェクトであることに注意してください。

次に、fields パラメーターのフォーマット方法の詳細について説明し、続いて、応答で正確に返される内容について詳しく説明します。

フィールドの要約パラメーター構文

フィールド要求パラメーター値の形式は、XPath 構文に大まかに基づいています。サポートされている構文を以下に要約し、次のセクションで追加の例を示します。

  1. 複数のフィールドを選択するには、コンマ区切りのリストを使用します。

  2. a/b を使用して、フィールド a にネストされているフィールド b を選択します。a/b/c を使用して、b にネストされたフィールド c を選択します。

  3. サブセレクターを使用して、式を括弧 "( )" に配置することにより、配列またはオブジェクトの特定のサブフィールドのセットを要求します。

  4. 必要に応じて、フィールドの選択にワイルドカードを使用します。

Hub OpenAPI 仕様 (OAS)Hub のソート構文