REST API のカスタムフィールド

このページでは、YouTrack のカスタムフィールドの階層と、CustomField、ProjectCustomField、IssueCustomField エンティティが互いにどのように異なるかについて説明します。

CustomField

CustomField は、name や fieldType などの基本的な属性を含む共通のカスタムフィールドを定義するエンティティです。instances プロパティには、さまざまなプロジェクトでのこのフィールドの設定が含まれています。

CustomField 属性の完全なリストについては、CustomField を参照してください。

次のサンプルは、YouTrack のすべてのカスタムフィールドを取得する方法を示しています。デフォルトでは、YouTrack は要求されたエンティティの $type 属性のみを返します。カスタムフィールドに関する詳細情報を取得するには、要求の fields パラメーターで返されるエンティティ属性のリストを明示的に提供します。$type 属性は、明示的に指定したかどうかに関係なく、応答に表示されます。

サンプルリクエスト

            curl -X GET \
            'https://example.youtrack.cloud/api/admin/customFieldSettings/customFields?fields=id,name,aliases,instances(id,project(id,name))' \
            -H 'Accept: application/json' \
            -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
            -H 'Cache-Control: no-cache' \
            -H 'Content-Type: application/json'
        

サンプルレスポンスボディ

            [
                ...
                {
                    "name": "Priority",
                    "aliases": null,
                    "instances": [
                        {
                            "project": {
                                "name": "Sample Project",
                                "id": "0-0",
                                "$type": "Project"
                            },
                            "id": "92-1",
                            "$type": "EnumProjectCustomField"
                        },
                        ...
                    ],
                    "id": "58-1",
                    "$type": "CustomField"
                },
                ...
                {
                    "name": "Assignee",
                    "aliases": "for, assigned to",
                    "instances": [
                        {
                            "project": {
                                "name": "Sample Project",
                                "id": "0-0",
                                "$type": "Project"
                            },
                            "id": "94-0",
                            "$type": "UserProjectCustomField"
                        },
                        ...
                    ],
                    "id": "58-4",
                    "$type": "CustomField"
                },
                ...
            ]
        

ProjectCustomField

ProjectCustomField は、特定のプロジェクト (project) の CustomField (field 属性) の設定 (可能な値のセット (bundle)、フィールドを空にできるかどうか (canBeEmpty) など) を含むエンティティです。

ProjectCustomField 属性の完全なリストについては、ProjectCustomField を参照してください。

次のサンプルは、特定のプロジェクトですべてのカスタムフィールドとその設定を取得する方法を示しています。

サンプルリクエスト

            curl -X GET \
            'https://example.youtrack.cloud/api/admin/projects/0-0/customFields?fields=id,canBeEmpty,emptyFieldText,project(id,name),field(id,name,fieldType(id,valueType,isMultiValue))' \
            -H 'Accept: application/json' \
            -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
            -H 'Cache-Control: no-cache' \
            -H 'Content-Type: application/json'
        

サンプルレスポンスボディ

            [
                ...
                {
                    "field": {
                        "name": "Priority",
                        "fieldType": {
                            "valueType": "enum",
                            "isMultiValue": false,
                            "id": "enum[1]",
                            "$type": "FieldType"
                        },
                        "id": "58-1",
                        "$type": "CustomField"
                    },
                    "project": {
                        "name": "Sample Project",
                        "id": "0-0",
                        "$type": "Project"
                    },
                    "emptyFieldText": "No Priority",
                    "canBeEmpty": false,
                    "id": "92-1",
                    "$type": "EnumProjectCustomField"
                },
                ...
                {
                    "field":{
                        "id":"58-4",
                        "name":"Assignee",
                        "fieldType": {
                            "valueType": "user",
                            "isMultiValue": false,
                            "id": "user[1]",
                            "$type": "FieldType"
                        },
                        "$type":"CustomField"
                    },
                    "project": {
                        "name": "Sample Project",
                        "id": "0-0",
                        "$type": "Project"
                    },
                    "emptyFieldText":"Unassigned",
                    "canBeEmpty":true,
                    "id":"94-0",
                    "$type":"UserProjectCustomField"
            },
                ...
            ]
        

ProjectCustomField エンティティには、直接の multi プロパティはありません。プロジェクトフィールドに複数の値が格納されているかどうかを確認するには、リンクされた CustomField の field.fieldType.isMultiValue 属性を要求してください。field.fieldType.id の値には、カーディナリティ接尾辞も含まれます。たとえば、複数値ユーザーフィールドの場合は user[*] となります。

IssueCustomField

IssueCustomField エンティティには、特定の課題の ProjectCustomField （projectCustomField）の値（value 属性）が含まれています。値は、単純なもの（たとえば、string または integer）、既存のエンティティへのリンク（Assignee フィールドの特定のユーザーへのリンク）、または値のコレクション（Affected versions フィールド）にすることができます。

value 属性の正確な型は、IssueCustomField の $type に依存します。例: ユーザーフィールドは User エンティティを返し、enum および state フィールドはバンドル要素を返し、version フィールドはバンドル要素のコレクションを返すことができ、simple フィールドはプリミティブ値を返します。

IssueCustomField 属性の完全なリストについては、IssueCustomField を参照してください。

特定の課題に関するカスタムフィールドを取得するには、GET リクエストを /api/issues/{issueID}/customFields に送信します。

次のサンプルは、特定の課題ですべてのカスタムフィールドとその値を取得する方法を示しています。

サンプルリクエスト

            curl -X GET \
            'https://example.youtrack.cloud/api/issues/2-7/customFields?fields=id,value(id,name,login,fullName),projectCustomField(id,field(id,name))' \
            -H 'Accept: application/json' \
            -H 'Authorization: Bearer perm:am9obi5kb2U=.UG9zdG1hbiBKb2huIERvZQ==.jJe0eYhhkV271j1lCpfknNYOEakNk7' \
            -H 'Cache-Control: no-cache' \
            -H 'Content-Type: application/json'
        

サンプルレスポンスボディ

            [
                {
                    "projectCustomField": {
                        "field": {
                            "name": "Priority",
                            "id": "58-1",
                            "$type": "CustomField"
                        },
                        "id": "92-1",
                        "$type": "EnumProjectCustomField"
                    },
                    "value": {
                        "name": "Major",
                        "id": "67-2",
                        "$type": "EnumBundleElement"
                    },
                    "id": "92-1",
                    "$type": "SingleEnumIssueCustomField"
                },
                ...
                {
                    "projectCustomField": {
                        "field": {
                            "name": "Assignee",
                            "id": "58-4",
                            "$type": "CustomField"
                        },
                        "id": "94-0",
                        "$type": "UserProjectCustomField"
                    },
                    "value":{
                        "name": "Jane Doe",
                        "fullName": "Jane Doe",
                        "login": "jane.doe",
                        "id": "1-3",
                        "$type": "User"
                    },
                    "id": "94-0",
                    "$type": "SingleUserIssueCustomField"
                },
                ...
            ]
        

この応答では、Priority フィールドは EnumBundleElement を返し、Assignee フィールドは User エンティティを返します。その他のカスタムフィールドは、IssueCustomField $type に応じて異なる値型を返すことができます。

特定のカスタムフィールド値を要求および解釈する方法のその他の例については、課題カスタムフィールドの値を取得するを参照してください。

その他のフィールドタイプの例

以下の例は、他の IssueCustomField 型における value 属性の一般的な形状を示しています。fields パラメーターでは、必要なネストされた値属性のみを要求してください。

複数値フィールドは値の配列を返します。例: 複数値バージョンフィールドは以下を返すことができます。

                {
                    "name": "Fix versions",
                    "value": [
                        {
                            "name": "2026.1",
                            "id": "133-19",
                            "$type": "VersionBundleElement"
                        },
                        {
                            "name": "2026.2",
                            "id": "133-24",
                            "$type": "VersionBundleElement"
                        }
                    ],
                    "id": "92-4",
                    "$type": "MultiVersionIssueCustomField"
                }
            

State、build、owned、enum、version、group、user フィールドは、バンドル要素またはエンティティを返します。正確なエンティティタイプは、フィールドタイプによって異なります。

                {
                    "name": "State",
                    "value": {
                        "name": "In Progress",
                        "isResolved": false,
                        "id": "78-2",
                        "$type": "StateBundleElement"
                    },
                    "id": "92-3",
                    "$type": "StateIssueCustomField"
                }
            

                {
                    "name": "Fixed in build",
                    "value": {
                        "name": "2026.1.45678",
                        "id": "95-12",
                        "$type": "BuildBundleElement"
                    },
                    "id": "92-8",
                    "$type": "SingleBuildIssueCustomField"
                }
            

単純フィールドはプリミティブ値を返します。日付フィールドと日時フィールドはミリ秒単位のタイムスタンプを返します。

                {
                    "name": "Customer email",
                    "value": "jane.doe@example.com",
                    "id": "92-9",
                    "$type": "SimpleIssueCustomField"
                }
            

                {
                    "name": "Due Date",
                    "value": 1782864000000,
                    "id": "92-10",
                    "$type": "DateIssueCustomField"
                }
            

期間フィールドは PeriodValue オブジェクトを返します。

                {
                    "name": "Estimation",
                    "value": {
                        "minutes": 150,
                        "presentation": "2h 30m",
                        "id": "150-1",
                        "$type": "PeriodValue"
                    },
                    "id": "92-11",
                    "$type": "PeriodIssueCustomField"
                }
            

テキストフィールドは、ソーステキストとレンダリングされた Markdown を含むテキスト値オブジェクトを返します。

                {
                    "name": "Release notes",
                    "value": {
                        "text": "Fixed in the latest build.",
                        "markdownText": "<p>Fixed in the latest build.</p>",
                        "id": "150-2",
                        "$type": "TextFieldValue"
                    },
                    "id": "92-12",
                    "$type": "TextIssueCustomField"
                }
            

カスタムフィールドの $type マッピング

次の表は、サポートされている課題のカスタムフィールドとそれに対応する $type 値の間のマッピングを示しています。課題のカスタムフィールドを設定または更新する必要がある場合は、POST リクエストで $type 値を指定する必要があります。

ProjectCustomField および $type は、すべてのフィールドタイプにおいて、単一値フィールドと複数値フィールドを区別しません。例: version[1] と version[*] はどちらも VersionProjectCustomField を使用します。複数値プロジェクトフィールドを識別する必要がある場合は、field.fieldType.isMultiValue または field.fieldType.id の [*] 接尾辞を使用してください。

カスタムフィールドタイプ	IssueCustomField `$type`	ProjectCustomField `$type`
`enum[1]`	`SingleEnumIssueCustomField`	`EnumProjectCustomField`
`enum[*]`	`MultiEnumIssueCustomField`	`EnumProjectCustomField`
`build[1]`	`SingleBuildIssueCustomField`	`BuildProjectCustomField`
`build[*]`	`MultiBuildIssueCustomField`	`BuildProjectCustomField`
`state[1]`	`StateIssueCustomField`	`StateProjectCustomField`
`version[1]`	`SingleVersionIssueCustomField`	`VersionProjectCustomField`
`version[*]`	`MultiVersionIssueCustomField`	`VersionProjectCustomField`
`ownedField[1]`	`SingleOwnedIssueCustomField`	`OwnedProjectCustomField`
`ownedField[*]`	`MultiOwnedIssueCustomField`	`OwnedProjectCustomField`
`user[1]`	`SingleUserIssueCustomField`	`UserProjectCustomField`
`user[*]`	`MultiUserIssueCustomField`	`UserProjectCustomField`
`group[1]`	`SingleGroupIssueCustomField`	`GroupProjectCustomField`
`group[*]`	`MultiGroupIssueCustomField`	`GroupProjectCustomField`
`integer`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`float`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`date`	`DateIssueCustomField`	`SimpleProjectCustomField`
`date and time`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`period`	`PeriodIssueCustomField`	`PeriodProjectCustomField`
`string`	`SimpleIssueCustomField`	`SimpleProjectCustomField`
`text`	`TextIssueCustomField`	`TextProjectCustomField`

カスタムフィールドを設定または更新する場合、value 属性の形式はフィールドタイプによって異なります。

単一値の列挙型、ビルド、状態、バージョン、所有、ユーザー、グループフィールドは、単一値オブジェクトを使用します。たとえば、列挙値の場合は {"name": "Major"}、ユーザーの場合は {"login": "jane.doe"} です。
複数値を持つ列挙型、ビルド、バージョン、所有、ユーザー、グループフィールドは、値オブジェクトの配列を使用します。
整数型、浮動小数点型、文字列型のフィールドは、プリミティブ値を使用します。
日付および日時フィールドでは、ミリ秒単位のタイムスタンプが使用されます。
期間フィールドでは、PeriodValue オブジェクトを使用します。たとえば、{"minutes": 150} または {"presentation": "2h 30m"} です。
テキストフィールドは、たとえば {"text": "Some text"} のように TextFieldValue オブジェクトを使用します。

2026 年 9 月 10 日

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

REST API のカスタムフィールド

CustomField

サンプルリクエスト

サンプルレスポンスボディ

ProjectCustomField

サンプルリクエスト

サンプルレスポンスボディ

IssueCustomField

サンプルリクエスト

サンプルレスポンスボディ

その他のフィールドタイプの例

カスタムフィールドの $type マッピング

関連ページ：