添付ファイル API

Yokohama API リファレンス

Release

yokohama

ft:locale

ja-JP

ft:publication_title

Yokohama API リファレンス

ft:clusterId

crapiref

bundleId

crapiref

workflow

Creator

添付ファイル API

リリースバージョン: Yokohama

更新日 2025年01月30日

所要時間：30分

添付ファイル API は、添付ファイルをアップロードしてクエリできるようにするエンドポイントを提供します。

要求ごとに 1 つのファイルをアップロードまたは取得できます。

添付ファイル API は、最大ファイルサイズや許可される添付ファイルタイプなど、アップロードされたファイルに関するシステム制限に従います。これらの設定は、プロパティ com.glide.attachment.max_size、デフォルトで 1024 MB、および glide.attachment.extensions を使用して制御できます。

注:

添付ファイル API は、すべてのコンテンツタイプ値 (*/*) を受け入れます。添付ファイルをアップロードするときのファイルコンテンツタイプを指定します。コンテンツタイプはファイルメタデータとともに保存されるため、他のツールはファイルを正しく識別して解析できます。

次のビデオでは、添付ファイル API について詳しく説明しています。

添付ファイル API ロールの要件

添付ファイルを作成するには、 ServiceNow での HTTP 要求の認証に使用されるユーザーレコードに、添付ファイル [sys_attachment] レコードの作成に必要なロールが必要です。また、インシデントレコードに添付ファイルを追加するための itil ロールなど、ターゲットテーブルのレコードの読み取りと書き込みに必要なロールも必要です。

デフォルトでは、ユーザーが添付ファイルを追加できるロールは 1 つではありません。添付ファイルの追加を明示的に許可するロールを作成し、要求を行うために使用しているユーザーアカウントにこのロールをアサインすることができます。

添付ファイル:DELETE /now/attachment/{sys_id}

このメソッドは、特定のsys_id値を持つ添付ファイルを削除します。

URL 形式

バージョニングされた URL: /api/now/v1/attachment/{sys_id}

デフォルト URL: /api/now/attachment/{sys_id}

注:

使用可能なバージョンは、REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 1. パスパラメーター
名前	説明
sys_id	削除する添付ファイルのSys_id値。データタイプ：文字列

表 : 2. クエリパラメーター
名前	説明
なし

表 : 3. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

次の要求ヘッダーと応答ヘッダーは、この HTTP アクションにのみ適用されるか、別の方法でこのアクションに適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 4. 要求ヘッダー
ヘッダー	説明
なし

表 : 5. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 6. ステータスコード
ステータスコード	説明
204	要求が正常に実行されたことを示します。
401	権限がありません。ユーザー認証情報が正しくないか、渡されていません。
404	見つかりません。要求されたアイテムが見つかりませんでした。
500	内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

応答本文のパラメーター (JSON または XML)


名前	説明
なし

cURL 要求

curl "https://instance.servicenow.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5" \
--request DELETE \
--user 'username':'password'

""

添付ファイル:GET /now/attachment

複数の添付ファイルのメタデータを返します。

URL 形式

バージョニングされた URL: api/now/v1/attachment

デフォルト URL: api/now/attachment

注:

サポートされている要求パラメーター

表 : 7. パスパラメーター
名前	説明
なし

表 : 8. クエリパラメーター
名前	説明
sysparm_limit	ページネーションに適用する制限。注: `sysparm_limit`値が異常に大きいと、システムのパフォーマンスに影響を与える可能性があります。データタイプ：文字列デフォルト：1000
sysparm_offset	クエリから除外するレコードの数。パラメーターで指定した数よりも多くのレコードを取得するには、このパラメーターを使用しますsysparm_limit たとえば、 sysparm_limit が 500 に設定されていても、クエリーする追加のレコードがある場合、 sysparm_offset パラメーター値 500 を指定すると、2 番目のレコードセットを取得できます。データタイプ：文字列デフォルト：0
sysparm_query	エンコードクエリ。添付ファイル API のクエリは、添付ファイル [sys_attachment] テーブルに関連しています。例： (sysparm_query=file_name=attachment.doc) エンコードされたクエリは、順番をサポートします。特定のフィールドに基づいて応答をソートするには、sysparm_queryで ORDERBY 句と ORDERBYDESC 句を使用します。たとえば、 `sysparm_query=ORDERBYfile_name^ORDERBYDESCtable_Name` では、最初に名前で結果を昇順に並べ替え、次にテーブル名で降順に並べ替えます。データタイプ：文字列

表 : 9. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

表 : 10. 要求ヘッダー
ヘッダー	説明
受容	応答本文のデータ形式。サポートされているタイプ: application/json または application/xml。デフォルト： application/json

表 : 11. 応答ヘッダー
ヘッダー	説明
Content-Type	応答のコンテンツタイプ。メタデータ要求の場合、これは添付ファイルのコンテンツタイプではなく、メタデータのコンテンツタイプです。
リンク	添付ファイルをダウンロードするためのリンク。

ステータスコード

表 : 12. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
401	権限がありません。ユーザー認証情報が正しくないか、渡されていません。
500	内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

応答本文のパラメーター (JSON または XML)


名前	説明
返される情報は、選択した添付ファイルによって異なります。

cURL 要求

curl "https://instance.servicenow.com/api/now/attachment?sysparm_limit=1" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": [
    {
      "table_sys_id": "5054b6f8c0a800060056addcf551ecf8",
      "size_bytes": "462",
      "download_link": "https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file",
      "sys_updated_on": "2009-05-21 04:12:21",
      "sys_id": "615ea769c0a80166001cf5f2367302f5",
      "image_height": "",
      "sys_created_on": "2009-05-21 04:12:21",
      "file_name": "blocks.swf",
      "sys_created_by": "glide.maint",
      "compressed": "true",
      "average_image_color": "",
      "sys_updated_by": "glide.maint",
      "sys_tags": "",
      "table_name": "content_block_programmatic",
      "image_width": "",
      "sys_mod_count": "0",
      "content_type": "application/x-shockwave-flash",
      "size_compressed": "485"
    }
  ]
}

添付ファイル:GET /now/attachment/{sys_id}/file

特定のsys_id値を持つバイナリファイルの添付ファイルを返します。

URL 形式

バージョニングされた URL: /api/now/v1/attachment/{sys_id}/file

デフォルト URL: /api/now/attachment/{sys_id}/file

注:

サポートされている要求パラメーター

表 : 13. パスパラメーター
名前	説明
sys_id	バイナリデータを返す添付ファイルレコードのSys_id。

表 : 14. クエリパラメーター
名前	説明
なし

表 : 15. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

表 : 16. 要求ヘッダー
ヘッダー	説明
受容	応答本文のデータ形式。たとえば、 `image/jpeg` または `image/png` を使用して、JPEG または PNG 画像ファイルを排他的に受け入れます。すべての画像タイプを許可するには、 `image/` を指定します。任意のファイルタイプを許可するには、 `/` を指定します。デフォルト値:/*

表 : 17. 応答ヘッダー
ヘッダー	説明
X-Attachment-Metadata	サイズ、名前、ファイルタイプなど、返されたファイルに関するメタデータ。

ステータスコード

表 : 18. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不正な要求タイプまたは不正な形式の要求が検出されました。
401	権限がありません。ユーザー認証情報が正しくないか、渡されていません。
500	内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

応答本文のパラメーター (JSON または XML)


名前	説明
バイナリファイルの添付

cURL 要求

curl "https://instance.servicenow.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file" \
--request GET \
--header "Accept:*/*" \
--user "username":"password"

Binary response not shown.

添付ファイル:GET /now/attachment/{sys_id}

特定のsys_id値を持つ添付ファイルのメタデータを返します。

URL 形式

バージョニングされた URL: /api/now/v1/attachment/{sys_id}

デフォルト URL: /api/now/attachment/{sys_id}

注:

サポートされている要求パラメーター

表 : 19. パスパラメーター
名前	説明
sys_id	メタデータを取得する添付ファイルレコードのSys_id。

表 : 20. クエリパラメーター
名前	説明
なし

表 : 21. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

表 : 22. 要求ヘッダー
ヘッダー	説明
受容	応答本文のデータ形式。サポートされているタイプ: application/json または application/xml。デフォルト： application/json

表 : 23. 応答ヘッダー
ヘッダー	説明
Content-Type	応答のコンテンツタイプ。メタデータ要求の場合、これは添付ファイルのコンテンツタイプではなく、メタデータのコンテンツタイプです。

ステータスコード

表 : 24. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
401	権限がありません。ユーザー認証情報が正しくないか、渡されていません。
404	指定した添付ファイルが存在しないか、現在のユーザーがアクセスできないことを示します。
500	内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

応答本文のパラメーター (JSON または XML)


名前	説明
指定された添付ファイルに固有のメタデータ。

cURL 要求

curl "https://instance.servicenow.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "table_sys_id": "5054b6f8c0a800060056addcf551ecf8",
    "size_bytes": "462",
    "download_link": "https://instance.service-now.com/api/now/attachment/615ea769c0a80166001cf5f2367302f5/file",
    "sys_updated_on": "2009-05-21 04:12:21",
    "sys_id": "615ea769c0a80166001cf5f2367302f5",
    "image_height": "",
    "sys_created_on": "2009-05-21 04:12:21",
    "file_name": "blocks.swf",
    "sys_created_by": "glide.maint",
    "compressed": "true",
    "average_image_color": "",
    "sys_updated_by": "glide.maint",
    "sys_tags": "",
    "table_name": "content_block_programmatic",
    "image_width": "",
    "sys_mod_count": "0",
    "content_type": "application/x-shockwave-flash",
    "size_compressed": "485"
  }
}

添付ファイル:POST /now/attachment/file

指定されたバイナリファイルを添付ファイルとして指定されたレコードにアップロードします。

注:

添付するファイルは、渡された要求パラメーターリストの最後のパラメーターの後に指定する必要があります。

URL 形式

バージョニングされた URL: /api/now/v1/attachment/file

デフォルト URL: /api/now/attachment/file

注:

サポートされている要求パラメーター

表 : 25. パスパラメーター
名前	説明
なし

表 : 26. クエリパラメーター
名前	説明
creation_time	添付ファイルの作成日時。このパラメーターを使用して、 Now Mobile アプリがオフラインになっていて、後で添付ファイルがレコードにアップロードされるときに、添付ファイルの作成時刻をキャプチャします。データタイプ：文字列デフォルト:現在の日付と時刻。
encryption_context	暗号化コンテキストレコードのSys_id。指定した暗号化コンテキストを持つユーザーのみが添付ファイルにアクセスできるようにするには、このパラメーターを指定します。暗号化コンテキストレコードの詳細については、「 Field Encryption」を参照してください。データタイプ：文字列デフォルト:ファイルは、ユーザーがアクセス可能な暗号化コンテキストを使用して暗号化されます。それ以外の場合、添付ファイルは暗号化コンテキストで暗号化されません。
file_name	必須。添付ファイルに付ける名前。データタイプ：文字列
table_name	必須。ファイルを添付するテーブルの名前。データタイプ：文字列
table_sys_id	必須。ファイルを添付する、 table_name で指定されたテーブル内のレコードのSys_id。データタイプ：文字列

表 : 27. 要求本文パラメーター (XML または JSON)
名前	説明
<文字列>	指定されたレコードに添付するバイナリファイルへのパス。

ヘッダー

表 : 28. 要求ヘッダー
ヘッダー	説明
受容	応答本文のデータ形式。サポートされているタイプ: application/json または application/xml。デフォルト： application/json
Content-Type	添付するファイルのコンテンツタイプ (image/jpeg や / など)。このヘッダーは、添付ファイルを投稿するために必須です。

表 : 29. 応答ヘッダー
ヘッダー	説明
場所	新しい添付ファイルの URL。

ステータスコード

表 : 30. ステータスコード
ステータスコード	説明
201	クエリが正常に実行されたことを示します。
400	要求に 1 つ以上の必須パラメーターがなかったことを示します。
404	table_nameで指定されたレコードとtable_sys_idパラメーターが存在しないか、現在のユーザーがアクセスできないことを示します。
500	内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

応答本文のパラメーター (JSON または XML)


要素	説明
結果	要求された添付ファイルのメタデータ。データタイプ：オブジェクト "result": { "average_image_color": "String", "compressed": "String", "content_type": "String", "created_by_name": "String", "download_link": "String", "file_name": "String", "image_height": "String", "image_width": "String", "size_bytes": "String", "size_compressed": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_mod_count": "String", "sys_tags": "String", "sys_updated_by": "String", "sys_updated_on": "String", "table_name": "String", "table_sys_id": "String", "updated_by_name": "String" }
result.average_image_color	添付ファイルが画像の場合、すべての色の合計。データタイプ：文字列単位:RGB またはピクセル数。
result.compressed	添付ファイルが圧縮されているかどうかを示すフラグ。可能な値： true:ファイルは圧縮されています。 false:ファイルは圧縮されていません。データタイプ：文字列
result.content_type	画像や jpeg、application/x-shockwave-flash など、関連する添付ファイルのコンテンツタイプ。データタイプ：文字列
result.created_by_name	最初に添付ファイルを作成したエンティティのフルネーム。データタイプ：文字列
result.download_link	ServiceNowインスタンスの添付ファイルのダウンロード URL。データタイプ：文字列
result.file_name	添付ファイルのファイル名。データタイプ：文字列
result.image_height	画像ファイルの場合は、画像の高さ。データタイプ：文字列単位:ピクセル
result.image_width	画像ファイルの場合、画像の幅。データタイプ：文字列単位:ピクセル
result.size_bytes	添付ファイルのサイズ。データタイプ：文字列単位:バイト
result.size_compressed	圧縮された添付ファイルのサイズ。ファイルが圧縮されていない場合は空です。データタイプ：文字列単位:バイト
result.sys_created_by	添付ファイルを最初に作成したエンティティ。データタイプ：文字列
result.sys_created_on	添付ファイルが最初にインスタンスに保存された日時。データタイプ：文字列
result.sys_id	添付ファイルのSys_id。データタイプ：文字列
result.sys_mod_count	添付ファイルが変更された (インスタンスにアップロードされた) 回数。データタイプ：文字列
result.sys_tags	添付ファイルに関連付けられているシステムタグ。データタイプ：文字列
result.sys_updated_by	添付ファイルを最後に更新したエンティティ。データタイプ：文字列
result.sys_updated_on	添付ファイルの最終更新日時。データタイプ：文字列
result.table_name	添付ファイルが関連付けられているテーブルの名前。データタイプ：文字列
result.table_sys_id	添付ファイルに関連付けられているテーブルのSys_id。データタイプ：文字列
result.updated_by_name	添付ファイルを最後に更新したエンティティのフルネーム。データタイプ：文字列

cURL 要求

curl "https://instance.servicenow.com/api/now/attachment/file?table_name=incident&table_sys_id=d71f7935c0a8016700802b64c67c11c6&file_name=Issue_screenshot" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type: image/jpeg" \
--user "username":"password" \
--data-binary "@ location of the file on file system"

{
  "result": {
    "table_sys_id": "d71f7935c0a8016700802b64c67c11c6",
    "size_bytes": "36597",
    "download_link": "https://instance.servicenow.com/api/now/attachment/6ea10fe64f411200adf9f8e18110c739/file",
    "sys_updated_on": "2016-01-22 15:14:07",
    "sys_id": "6ea10fe64f411200adf9f8e18110c739",
    "image_height": "",
    "sys_created_on": "2016-01-22 15:14:07",
    "file_name": "Issue_screenshot",
    "sys_created_by": "admin",
    "compressed": "true",
    "average_image_color": "",
    "sys_updated_by": "admin",
    "sys_tags": "",
    "table_name": "incident",
    "image_width": "",
    "sys_mod_count": "0",
    "content_type": "image/jpeg",
    "size_compressed": "25130"
  }
}

添付ファイル:POST /now/attachment/upload

マルチパートの添付ファイルをアップロードします。

マルチパート POST メソッドは、パラメーターを受け入れません。フォーム本文内でテーブル名とレコードsys_id値を指定する必要があります。multipart/form-data 要求のサンプルについては、cURL の例を参照してください。

重要:

マルチパート POST を使用する場合は、ファイルコンテンツがメッセージの最後の部分にのみ含まれていることを確認してください。前のパーツには、テーブル名やレコードsys_idなどのメタデータのみを含める必要があります。

URL 形式

バージョニングされた URL: /api/now/v1/attachment/upload

デフォルト URL: /api/now/attachment/upload

注:

サポートされている要求パラメーター

表 : 31. パスパラメーター
名前	説明
なし

表 : 32. クエリパラメーター
名前	説明
なし

表 : 33. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

表 : 34. 要求ヘッダー
ヘッダー	説明
受容	応答本文のデータ形式。サポートされているタイプ: application/json または application/xml。デフォルト： application/json
Content-Type	要求のコンテンツタイプ。multipart POST メソッドを使用する場合は、この値を multipart/form-data に設定します。

表 : 35. 応答ヘッダー
ヘッダー	説明
場所	新しい添付ファイルの URL。

ステータスコード

表 : 36. ステータスコード
ステータスコード	説明
201	クエリが正常に実行されたことを示します。
400	要求が正しくありません。不正な要求タイプまたは不正な形式の要求が検出されました。
401	権限がありません。ユーザー認証情報が正しくないか、渡されていません。
404	見つかりません。要求されたアイテムが見つかりませんでした。
500	内部サーバーエラー要求の処理中に予期しないエラーが発生しました。応答には、エラーに関する追加情報が含まれています。

応答本文のパラメーター (JSON または XML)


要素	説明
結果	要求された添付ファイルのメタデータ。データタイプ：オブジェクト "result": { "average_image_color": "String", "compressed": "String", "content_type": "String", "created_by_name": "String", "download_link": "String", "file_name": "String", "image_height": "String", "image_width": "String", "size_bytes": "String", "size_compressed": "String", "sys_created_by": "String", "sys_created_on": "String", "sys_id": "String", "sys_mod_count": "String", "sys_tags": "String", "sys_updated_by": "String", "sys_updated_on": "String", "table_name": "String", "table_sys_id": "String", "updated_by_name": "String" }
result.average_image_color	添付ファイルが画像の場合、すべての色の合計。データタイプ：文字列単位:RGB またはピクセル数。
result.compressed	添付ファイルが圧縮されているかどうかを示すフラグ。可能な値： true:ファイルは圧縮されています。 false:ファイルは圧縮されていません。データタイプ：文字列
result.content_type	画像や jpeg、application/x-shockwave-flash など、関連する添付ファイルのコンテンツタイプ。データタイプ：文字列
result.created_by_name	最初に添付ファイルを作成したエンティティのフルネーム。データタイプ：文字列
result.download_link	ServiceNowインスタンスの添付ファイルのダウンロード URL。データタイプ：文字列
result.file_name	添付ファイルのファイル名。データタイプ：文字列
result.image_height	画像ファイルの場合は、画像の高さ。データタイプ：文字列単位:ピクセル
result.image_width	画像ファイルの場合、画像の幅。データタイプ：文字列単位:ピクセル
result.size_bytes	添付ファイルのサイズ。データタイプ：文字列単位:バイト
result.size_compressed	圧縮された添付ファイルのサイズ。ファイルが圧縮されていない場合は空です。データタイプ：文字列単位:バイト
result.sys_created_by	添付ファイルを最初に作成したエンティティ。データタイプ：文字列
result.sys_created_on	添付ファイルが最初にインスタンスに保存された日時。データタイプ：文字列
result.sys_id	添付ファイルのSys_id。データタイプ：文字列
result.sys_mod_count	添付ファイルが変更された (インスタンスにアップロードされた) 回数。データタイプ：文字列
result.sys_tags	添付ファイルに関連付けられているシステムタグ。データタイプ：文字列
result.sys_updated_by	添付ファイルを最後に更新したエンティティ。データタイプ：文字列
result.sys_updated_on	添付ファイルの最終更新日時。データタイプ：文字列
result.table_name	添付ファイルが関連付けられているテーブルの名前。データタイプ：文字列
result.table_sys_id	添付ファイルに関連付けられているテーブルのSys_id。データタイプ：文字列
result.updated_by_name	添付ファイルを最後に更新したエンティティのフルネーム。データタイプ：文字列

POST マルチパート必須値

添付ファイルをアップロードするマルチパート POST 要求を送信する場合は、URL パラメーターではなく、メッセージ本文に添付ファイルデータを含めます。メッセージ本文で次の値を指定する必要があります。

表 : 37. 必須値
値	説明
Content-Type	マルチパートアップロードのメッセージ本文に含まれるファイルのコンテンツタイプ。注: Content-Type は、フォームデータ内ではなく、POST メッセージのファイル部分内で定義する必要があります。マルチパートメッセージの例については、サンプルの POST マルチパートメッセージを参照してください。データタイプ：文字列
table_name	ファイルを添付するテーブルの名前。データタイプ：文字列
table_sys_id	ファイルを添付する、指定されたテーブルのレコードのSys_id。データタイプ：文字列

cURL 要求

curl "https://instance.servicenow.com/api/now/attachment/upload" \
--request POST \
--header "Accept:application/json"\
--user "username":"password"\
--header "Content-Type:multipart/form-data"\
 -F 'table_name=incident' \
 -F 'table_sys_id=d71f7935c0a8016700802b64c67c11c6'\
 -F 'uploadFile=@ location of the file on file system'
\

{
  "result": {
    "table_sys_id": "d71f7935c0a8016700802b64c67c11c6",
    "size_bytes": "36597",
    "download_link": "https://instance.service-now.com/api/now/attachment/994adbc64f511200adf9f8e18110c796/file",
    "sys_updated_on": "2016-02-02 14:00:21",
    "sys_id": "994adbc64f511200adf9f8e18110c796",
    "image_height": "",
    "sys_created_on": "2016-02-02 14:00:21",
    "file_name": "banner-CS0001345_v1_1.jpeg",
    "sys_created_by": "admin",
    "compressed": "true",
    "average_image_color": "",
    "sys_updated_by": "admin",
    "sys_tags": "",
    "table_name": "incident",
    "image_width": "",
    "sys_mod_count": "0",
    "content_type": "image/jpeg",
    "size_compressed": "25130"
  }
}