Media API

Media API 概要 (Media API Overview)

Media APIを使用すると、ユーザーはビデオを作成、アップロード、取得できます。また、ユーザーは出品に添付するためのドキュメントを作成、アップロード、取得することもできます。詳細については、ビジネスユースケースを参照してください。

ヒント: image リソースの使用方法の詳細については、Selling Integration Guideの Managing images を参照してください。

ヒント: Media APIを使用したビデオの作成とアップロード方法、出品へのビデオの追加方法、およびeBayビデオサービスとのやり取りに関するベストプラクティスの詳細については、Selling Integration Guideの Managing videos を参照してください。

ヒント: document リソースの使用方法の詳細については、Selling Integration Guideの Managing documents を参照してください。

RESTful APIの使用方法の詳細については、Using eBay Restful APIs を参照してください。

技術概要 (Technical overview)

Media APIを使用すると、サードパーティの開発者は、以下のセクションにリストされている主要なメソッドとフィールドを使用して、ビデオとドキュメントを作成、アップロード、および取得できます。

メソッド

Media APIのメソッドは以下の通りです：

image
- createImageFromFile – このメソッドは、multipart/form-dataを使用して画像ファイルをeBay Picture Services (EPS) にアップロードします。
- createImageFromUrl – このメソッドは、指定されたURLからeBay Picture Services (EPS) に画像をアップロードします。
- getImage – このメソッドは、image_id を使用して画像の詳細を取得するために使用されます。この呼び出しは、アップロードされた画像にアクセスするために使用できるEPS画像URLと、画像の有効期限を取得します。
video
- createVideo – このメソッドは、ビデオを作成するために使用されます。送信されたメタデータに基づいて video ID を作成します。
- getVideo – このメソッドは、ビデオの video ID によってビデオを取得するために使用されます。
- uploadVideo – このメソッドは、ビデオソースと提供された video ID に基づいてビデオをアップロードします。
document
- createDocument – このメソッドは、ドキュメントのリソースを作成するために使用されます。送信されたメタデータに基づいて document ID を作成します。この呼び出しは、アップロードされるドキュメントをステージング（準備）しますが、ドキュメント自体は作成しません。
- createDocumentFromUrl - このメソッドは、提供されたURLからドキュメントをダウンロードし、ユーザーのアカウントに追加するために使用されます。
- getDocument – このメソッドは、document ID を使用してドキュメントの詳細を取得するために使用されます。この呼び出しは、ドキュメントリソースに関する基本的なメタデータを取得しますが、ドキュメントを（ダウンロード）取得するわけではありません。
- uploadDocument – このメソッドは、ドキュメントソースと提供された document ID に基づいてドキュメントをアップロードします。サポートされているファイルタイプには、.PDF、.JPEG、.JPG、.PNGが含まれます。

主要な画像フィールド

imageリソースで使用される主要なフィールドは以下の通りです：

注: サポートされている画像形式には、JPG、GIF、PNG、BMP、TIFF、AVIF、HEIC、WEBPが含まれます。

image_id - image_id は、成功した createImageFromFile または createImageFromUrl 呼び出しの location レスポンスヘッダーで返されます。getImage メソッド（このリソース内）を使用して画像URLを取得し、出品に画像を追加するために、返された画像ID値を必ずキャプチャしてください。詳細については、Managing images を参照してください。
imageUrl
- 成功した呼び出しのレスポンスペイロードで返される場合、このフィールドはアップロードされた画像にアクセスするためのEPS画像URLを表します。
- createImageFromUrl のリクエストペイロードの一部として使用される場合、imageUrl は、eBay Picture Services (EPS) にアップロードする自己ホスト画像の画像URLを提供します。

主要なビデオフィールド

videosリソースで使用される主要なフィールドは以下の通りです：

Classification – classification フィールドには、ビデオコンテンツの目的が含まれます。現在、ビデオで利用可能な分類は ITEM のみです。
Description – description フィールドには、作成またはアップロードされたビデオの説明が含まれます。これはオプションのフィールドであり、ビデオを作成するために入力する必要はありません。
Expiration Date – expirationDate フィールドには、協定世界時 (UTC) でのビデオの有効期限が含まれます。正常にアップロードされた各ビデオの有効期限は、最初のアップロード日から30日後です。
Input Stream – InputStream フィールドには、ビデオファイルの入力ストリームが含まれます。
Moderation – moderation コンテナは、ビデオがモデレーターによってブロックされた理由など、ビデオモデレーション情報を提供します。
Play URL – playURL フィールドには、ビデオコンテンツの再生可能なURLが含まれます。
Playlist – playList フィールドには、サポートされているプロトコルに基づいてストリーミングビデオのインスタンスにリンクする2つのURLが含まれます。
Protocol – protocol フィールドには、ビデオプレイリストのプロトコルが含まれます。サポートされているプロトコルは、DASH (Dynamic Adaptive Streaming over HTTP) と HLS (HTTP Live Streaming) です。
Size – size フィールドには、アップロードされるビデオのサイズ（バイト単位）が含まれます。
Status – status フィールドには、ビデオの現在のステータスが含まれます。利用可能なステータスは PENDING UPLOAD、PROCESSING、PROCESSING_FAILED、BLOCKED、および LIVE です。
- ビデオのステータスが PENDING_UPLOAD の場合、ビデオは video ID に関連付けられていますが、まだアップロードされていません。
- ビデオのアップロードが正常に完了した後、ステータスはビデオが LIVE、BLOCKED、または PROCESSING_FAILED のいずれかの最終状態に達するまで PROCESSING と表示されます。
- ビデオのステータスが LIVE の場合、これはファイルが処理され、正常にアップロードされたことを示します。DASHおよびHLSストリーミングビデオプロトコルでビデオのURLを提供する playList は、ビデオが正常にアップロードされた場合にのみ生成されます。
- ビデオファイルのアップロードに問題があり、ステータスが PROCESSING_FAILED になる場合があります。処理が失敗した場合、ファイルが破損している、大きすぎる、またはサイズがメタデータで提供されたものと一致しない可能性があります。ビデオのアップロード失敗の原因を特定するには、エラーメッセージを参照してください。
- このAPIは再開可能なアップロードをサポートしています。アップロード中にエラーが発生した場合、適切な Content-Range および Content-Length ヘッダーを使用して、受信したバイトからアップロードを再開できます。部分的にアップロードされたコンテンツに対して再アップロードを試みると、正しいバイト位置からアップロードを再開するための正しい Content-Range および Content-Length 値を含むエラーが発生します。
- ビデオにマルウェアが含まれている場合、またはビデオモデレーション機能によってブロックされている場合、ビデオは BLOCKED になる可能性があります。
Status Message – statusMessage フィールドには、ステータスに関する追加情報が含まれます。たとえば、処理が失敗した理由やビデオがブロックされた理由に関する情報などです。
Title – title フィールドには、ビデオのタイトルが含まれます。
Video ID – video ID フィールドには、作成されたビデオの一意のIDが含まれます。

主要なドキュメントフィールド

document リソースで使用される主要なフィールドは以下の通りです：

Document ID - documentId は、成功した createDocument 呼び出しのレスポンスで、レスポンスペイロードの documentId フィールドと location レスポンスヘッダーの両方で返されます。document リソースの他のメソッドを使用し、出品にドキュメントを追加するために、返されたドキュメントID値を必ずキャプチャしてください。
Document type - documentType フィールドには、アップロードされるドキュメントのタイプを指定する DocumentTypeEnum が含まれます。たとえば、SAFETY_DATA_SHEET などです。
Document URL - documentURLフィールドは、アカウントに追加されるドキュメントのURLを指定します。
Languages - この配列には、ドキュメントの言語を示す LanguageEnum が含まれます。

ビジネスユースケース (Business use cases)

セラーとバイヤーは、ビデオメディアを使用して商品や商品の機能を宣伝およびレビューしたり、ドキュメントメディアを使用してユーザーガイドや製品安全およびコンプライアンス文書を提供したりできます。

画像 (Images)

バイヤーは、商品画像やその他の広告手法に基づいて商品を選択することを選ぶ場合があります。公開されたオファー（出品）には、少なくとも1枚の写真が必要です。

画像を使用して商品を宣伝およびレビューすることは、セラーとバイヤーにいくつかの方法で利益をもたらします。例えば：

セラーは、出品で商品の正確な状態、サイズ、および用途を実証できます。
セラーは、商品や出品に関するより詳細な視覚情報を提供することで、他者と差別化を図ることができます。

ビデオ (Videos)

バイヤーは、商品画像やその他の広告手法に基づいてはわからない場合でも、その使用方法や状態のビデオデモンストレーションに基づいて商品を選択することを選ぶ場合があります。バイヤーはビデオを使用して商品をレビューすることもできます。

ビデオを使用して商品を宣伝およびレビューすることは、セラーとバイヤーにいくつかの方法で利益をもたらします。例えば：

セラーは、出品で商品の正確な状態、サイズ、および用途を実証できます。
セラーは、商品や出品に関するより詳細な視覚情報を提供することで、他者と差別化を図ることができます。
バイヤーは、サイズ、状態、機能、欠陥（ある場合）を含め、レビューして使用した商品の映像を提供できます。

ドキュメント (Documents)

セラーはドキュメントをアップロードして出品に添付できます。例えば、一般製品安全規則（GPSR）に必要な製品安全コンプライアンス文書やユーザーガイドなどです。

ドキュメントをアップロードするには、Media API のdocumentリソースを使用します。アップロードされたドキュメントを出品に追加するには、Trading API または Inventory API のいずれかを使用します。詳細については、Managing documents を参照してください。

API制限 (API restrictions)

このセクションでは、eBay Media APIの使用に関する制限について概説します。

ヒント: ビデオのフォーマット要件と制限の詳細については、eBayセラーセンターの Adding a video to your listing を参照するか、出品が投稿される地域の関連eBayサイトヘルプページをご覧ください。

SandboxとProductionデータ

eBay Sandbox環境のデータは静的です。範囲と数量が制限されている可能性があり、シミュレートされたデータや模擬データの場合があります。その結果、Production環境のデータにも同じ制限があると想定すべきではありません。アプリケーションが遭遇する可能性のあるデータのより広い範囲と変動性を予測するために、優れたコーディング手法を使用してください。