カスタムフィールドリストの取得
このインターフェースは、作成済みのカスタムフィールドを取得するために使用されます。
リクエストメソッド
get /custom_fields
リクエストパラメータ
| パラメータ名 | 必須 | タイプ | 説明 | 制限 |
|---|---|---|---|---|
| category | いいえ | 文字列 | 取得するカスタムフィールドのタイプ。詳細は以下を参照。デフォルトはチケット | 列挙型。取り得る値：["ticket", "customer", "organization"] 他の値が渡された場合、エラーにはなりませんが、ticketが渡されたものと同等になります |
category の説明
| オプション | 説明 |
|---|---|
| ticket | チケットカスタムフィールド |
| customer | 顧客カスタムフィールド |
| organization | 顧客会社カスタムフィールド |
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数 | 実行結果コード。1000は成功を表します |
| fields | 配列 | カスタムフィールドリスト。詳細は以下を参照 |
custom_fields 内の要素の説明
| 属性名 | タイプ | 説明 |
|---|---|---|
| id | 整数 | id |
| field_name | 文字列 | フィールド識別子 |
| field_label | 文字列 | フィールド表示名 |
| content_type | 文字列 | フィールドタイプ。詳細は以下を参照 |
| comment | 文字列 | フィールド備考 |
| updated_at | 日付時刻 | フィールドの最終更新日時 |
| options | 配列 | フィールドオプション。選択タイプのフィールドのみ返されます。詳細は以下を参照 |
| customer_permission | 文字列 | 顧客権限。顧客フィールドとチケットフィールドのみ返されます。詳細は以下を参照 |
| agent_permission | 文字列 | エージェント権限。顧客フィールドと顧客会社フィールドのみ返されます。詳細は以下を参照 |
| calculate_result_type | 文字列 | 計算フィールドの計算結果タイプ。計算フィールドのみ返されます。詳細は以下を参照 |
| #### content_type の取り得る値 |
| 値 | 説明 |
|---|---|
| text | 一行テキスト |
| area_text | 複数行テキスト |
| date | 日付 |
| time | 時間 |
| datetime | 日時 |
| link | ハイパーリンク |
| location | 地理位置 |
| number | 正の整数 |
| numeric | 数値 |
| droplist | ドロップダウンリスト |
| radio | 単一選択 |
| checkbox | 複数選択 |
| chained_droplist | 連動選択 |
| calculate | 計算フィールド |
- content_typeの取り得る値は機能の追加に伴い拡大する可能性があります。ビジネスロジックは新しいタイプへの拡張性を維持することをお勧めします。
- 各カスタムフィールドタイプのオプション構造の詳細は、例を参照してください。
calculate_result_type の取り得る値
| 値 | 説明 |
|---|---|
| numeric | 数字 |
| duration | 期間 |
| percentage | パーセンテージ |
options の説明
配列要素の構造
| 属性名 | タイプ | 説明 |
|---|---|---|
| title | 文字列 | オプションのテキスト説明 |
| value | 文字列 | オプションの値 |
| default | ブール値 | デフォルトオプションかどうか |
| is_hide | ブール値 | 非表示かどうか |
| subs | 配列 | 子オプション（連動選択フィールドのみに存在）。構造はoptionsと同じ |
customer_permission の取り得る値
| 値 | 説明 |
|---|---|
| none | 顧客には表示されない |
| readonly | 顧客は閲覧のみ可能、編集不可 |
| readwrite | 顧客は編集可能 |
| must | 顧客は必須入力 |
agent_permission の取り得る値
| 値 | 説明 |
|---|---|
| readonly | サポート担当者は閲覧のみ可能、編集不可 |
| readwrite | サポート担当者は編集可能 |
| must | サポート担当者は必須入力 |
| ### サンプル |
リクエスト
curl -s https://demo.udesk.cn/open_api_v1/custom_fields?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
&category=customer
レスポンス
{
"code": 1000,
"fields": [
{
"field_name": "TextField_1",
"field_label": "単行テキストフィールド",
"content_type": "text",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "readwrite",
"agent_permission": "must"
},
{
"field_name": "TextField_2",
"field_label": "複数行テキストフィールド",
"content_type": "area_text",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"cusotmer_permission": "readwrite",
"agent_permission": "readwrite"
},
{
"field_name": "TextField_3",
"field_label": "日付フィールド",
"content_type": "date",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "read",
"agent_permission": "must"
},
{
"field_name": "TextField_4",
"field_label": "日時フィールド",
"content_type": "datetime",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "read",
"agent_permission": "readwrite"
},
{
"field_name": "TextField_5",
"field_label": "リンクフィールド",
"content_type": "link",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "must",
"agent_permission": "readwrite"
},
{
"field_name": "TextField_6",
"field_label": "位置情報フィールド",
"content_type": "location",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "none",
"agent_permission": "readwrite"
},
{
"field_name": "TextField_7",
"field_label": "時間フィールド",
"content_type": "time",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "none",
"agent_permission": "readwrite"
},
{
"field_name": "TextField_8",
"field_label": "正の整数フィールド",
"content_type": "number",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "none",
"agent_permission": "must"
},
{
"field_name": "TextField_9",
"field_label": "数値フィールド",
"content_type": "numeric",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": null,
"customer_permission": "none",
"agent_permission": "readwrite"
},
{
"field_name": "SelectField_1",
"field_label": "ドロップダウンリストフィールド",
"content_type": "droplist",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"customer_permission": "read",
"agent_permission": "readwrite",
"options": [
{"title": "ドロップダウンオプション１", "value": "0"},
{"title": "ドロップダウンオプション２", "value": "1"}
]
},
{
"field_name": "SelectField_2",
"field_label": "ラジオボタンフィールド",
"content_type": "radio",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"customer_permission": "read",
"agent_permission": "readwrite",
"options": [
{"title": "ラジオボタンオプション１", "value": "1"},
{"title": "ラジオボタンオプション２", "value": "0"}
]
},
{
"field_name": "SelectField_3",
"field_label": "チェックボックスフィールド",
"content_type": "checkbox",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"customer_permission": "none",
"agent_permission": "must",
"options": [
{"title": "チェックボックスオプション１", "value": "3"},
{"title": "チェックボックスオプション２", "value": "4"},
{"title": "チェックボックスオプション３", "value": "1"},
{"title": "チェックボックスオプション４", "value": "7"}
]
},
{
"field_name": "SelectField_4",
"field_label": "カスケードフィールド",
"content_type": "chained_droplist",
"comment": null,
"updated_at": "2017-01-17T14:13:41.000+08:00",
"options": [
{"title": "北京市", "value": "0", "subs": [
{"title": "海淀区", "value": "0", "subs": [
{"title": "知春路", "value": "0"}
]}
]},
{"title": "天津市", "value": "0", "subs": [
{"title": "和平区", "value": "0"}
]}
],
"customer_permission": "none",
"agent_permission": "must"
}
]
}
単一カスタムフィールドの取得
このインターフェースは、単一のカスタムフィールドの詳細を取得するために使用されます。
リクエストメソッド
GET /custom_fields/:field_name
リクエストパラメータ
なし
レスポンスデータ
| 属性名 | タイプ | 説明 |
|---|---|---|
| code | 整数型 | 実行結果コード、1000は成功を表します |
| field | オブジェクト | 具体的なフィールドの意味については、上記のcustom_fields の要素説明を参照してください |
例
curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
レスポンス：
{
"code": 1000,
"field": {
"id": 1,
"field_name": "SelectField_1",
"field_label": "ドロップダウンリスト",
"content_type": "droplist",
"comment": "",
"updated_at": "2020-10-19T13:37:01.000+08:00",
"customer_permission": "readwrite",
"options": [
{
"title": "a",
"value": "0"
},
{
"title": "b",
"value": "1",
"default": true
},
{
"title": "c",
"value": "2"
}
]
}
}
カスタムフィールドの更新
このインターフェースは、指定されたカスタムフィールドを更新するために使用されます。現在、階層型フィールドはサポートされていません。
リクエストメソッド
PUT /custom_fields/:field_name
カスタムフィールドリストの取得インターフェースを使用して、すべてのカスタムフィールド情報を取得できます。
リクエストパラメータ
| パラメータ | 必須 | タイプ | 説明 | 制限 |
|---|---|---|---|---|
| field_name | はい | 文字列 | パラメータfield_nameは、カスタムフィールド設定ページの「フィールドID」列で取得するか、またはカスタムフィールドリストの取得APIインターフェースのレスポンスデータ内のfield_nameフィールドから取得できます。例：TextField_97、SelectField_166 |
|
| title | いいえ | 文字列 | カスタムフィールドのタイトル | |
| comment | いいえ | 文字列 | カスタムフィールドの備考 | |
| select_options | いいえ | 配列 | 選択型フィールドのオプションパラメータ。選択型フィールドのオプションを更新する場合にのみこのパラメータが必要です。選択型フィールドのオプションを更新しない場合は、このパラメータは入力不要です。 | |
| #### select_optionsの要素説明 | ||||
| > カスタムフィールドリストの取得 APIを通じてカスタムフィールド情報を取得できます |
| パラメータ | 必須 | タイプ | 説明 | 制約 |
|---|---|---|---|---|
| title | はい | 文字列 | オプションタイトル | |
| value | はい | 文字列 | オプション値 | 1.valueはシステムが自動生成するため、変更しないでください！ 2. 新しいオプションを追加する場合、valueオプションを渡す必要はありません！ |
| default | いいえ | ブール値 | デフォルト有効オプション | このパラメータを使用する場合、その値はtrueのみに設定できます |
valueはシステムが自動生成するため、変更しないでください！新しいオプションを追加する場合、
valueオプションを渡す必要はありません！
例
単一選択フィールドの更新
curl https://demo.udesk.cn/open_api_v1/custom_fields/SelectField_1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X PUT \
-H 'content-type:application/json' \
-d '
{
"title": "apiテストによるラジオボタンカスタムフィールドの変更",
"comment": "apiテストによるラジオボタンカスタムフィールドの変更",
"select_options": [
{
"title": "最初のオプション",
"value": "0",
"default": true
},
{
"title": "2番目のオプション",
"value": "1",
"is_hide": true
},
{
"title": "新規追加3番目のオプション",
}
]
}'
単一行テキストフィールドの更新
curl https://demo.udesk.cn/open_api_v1/custom_fields/TextField_1?email=admin@udesk.cn×tamp=1494474404&sign=6892f1b794071c260e1b1eac15df588fc919c9e86eb742affaa742ad6c03cb52&nonce=2d931510-d99f-494a-8c67-87feb05e1594&sign_version=v2
\
-X PUT \
-H 'content-type:application/json' \
-d '
{
"title": "apiテストによる単一行テキストカスタムフィールドの変更",
"comment": "apiテストによる単一行テキストカスタムフィールドの変更",
}'
戻り値
{
"code": 1000,
"message": "更新成功"
}
ドロップダウン大量オプションフィールドの対応オプションを取得
基本情報
Path： /open_api_v1/custom_fields/large_droplists/{field_id}
Method： POST
インターフェース説明： このインターフェースは、ドロップダウン大量オプションに対して、指定されたフィルタ条件に基づいて対応するオプションリストを取得します（ページング対応）
リクエストパラメータ
Headers
Content-Type: application/json
パスパラメータ
| パラメータ名 | 例 | 備考 |
|---|---|---|
| field_id | SelectField_1 | ドロップダウンフィールド名 |
クエリ
| パラメータ名 | 必須かどうか | 例 | 備考 |
|---|---|---|---|
| 必須 | test@udesk.cn | 管理者メールアドレス | |
| timestamp | 必須 | 1676616977 | タイムスタンプ |
| nonce | 必須 | 42a5551c | ランダム文字列 |
| sign_version | 必須 | v2 | |
| sign | 必須 | c24ad2a82901c1014572a51381ef0f32b278bd7ccf998af5a0ed592536e6ecc1 | 署名 |
ボディ
| 名前 | タイプ | 必須かどうか | デフォルト値 | 備考 | その他の情報 |
|---|---|---|---|---|---|
| title | string | 必須ではない | ドロップダウンオプションのタイトル | 完全一致検索 | |
| value | string | 必須ではない | ドロップダウンオプションの値 | ||
| create_range | string | 必須ではない | オプション作成時間範囲（YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm） | ||
| update_range | string | 必須ではない | オプション更新時間範囲（YYYY-MM-DD HH:mm,YYYY-MM-DD HH:mm） | ||
| page | number | 必須ではない | ページ番号（デフォルトは1） | ||
| per_page | number | 必須ではない | 1ページあたりのレコード数（最大100、デフォルト20） |
返却データ
| 名称 | タイプ | 必須 | デフォルト値 | 備考 | その他の情報 |
|---|---|---|---|---|---|
| code | number | 必須ではない | レスポンスステータスコード（1000は成功） | ||
| message | string | 必須ではない | レスポンスステータスの説明 | ||
| meta | object | 必須ではない | |||
| ├─ page | number | 必須ではない | ページ番号 | ||
| ├─ total_pages | number | 必須ではない | 総ページ数 | ||
| ├─ total_count | number | 必須ではない | 総レコード数 | ||
| select_options | object [] | 必須ではない | item タイプ: object | ||
| ├─ title | string | 必須ではない | オプションタイトル | ||
| ├─ value | string | 必須ではない | オプション値 | ||
| ├─ is_hide | boolean | 必須ではない | 非表示かどうか | ||
| ├─ default | boolean | 必須ではない | デフォルトオプションかどうか | ||
| ├─ created_at | string | 必須ではない | 作成日時 | ||
| ├─ updated_at | string | 必須ではない | 更新日時 |
リクエストメッセージ例
{
"page":1,
"update_range":"2023-02-17 08:00,2023-02-17 12:00"
}
レスポンスメッセージ例
{
"code":1000,
"message":"success",
"meta":{
"page":1,
"total_pages":10,
"total_count":300
},
"select_options":[
{
"title":"オプションタイトル",
"value":"1",
"is_hide":false,
"default":true,
"created_at":"2023-02-17 11:11:11",
"updated_at":"2023-02-17 11:11:11"
}
]
}
カスタムフィールド構造説明
説明
Udeskは現在、2種類のカスタムフィールド名をサポートしています SelectField TextField
| フィールド名 | タイプ | 説明 |
|---|---|---|
| SelectField_1 | 配列 | 選択型フィールドタイプ（ドロップダウン、チェックボックス、連携フィールドを含む）、タイプ名_ユニークID |
| TextField_1 | 文字列 | テキスト型フィールドタイプ、タイプ名_ユニークID |
コードエラーコード
| エラーコード | message情報 | exception:message情報 | 説明 |
|---|---|---|---|
| 2005 | 該当リソースが見つかりません | 指定されたカスタムフィールドが見つかりません | 渡されたfield_nameの形式が誤っているか、渡されたfield_nameに対応するリソースが見つかりません |
| 2015 | 管理者のみ操作可能です | 管理者のみ操作可能です | インターフェースを呼び出す際のメールアドレスは管理者メールアドレスである必要があります。管理者以外は操作できません |
| 2059 | open api署名が正しくありません | open api署名が正しくありません | open api署名が正しくありません。詳細は認証部分のドキュメントを参照してください |
| 2062 | パラメータエラー | パラメータselect_options配列内の要素のtitleは必須です | カスタムフィールドを変更する際、パラメータselect_options配列内の要素のtitleは必須です |
| パラメータエラー | field_nameパラメータは TextField | SelectField のみサポートしています |