ファイル
ベータ版APIのアクセスとテスト
このAPIは現在ベータ版として提供されています。最新の安定バージョンについては、以下の各ページをご確認ください。新しいファイルのアップロード、全てのファイルのメタデータのリスト、置換ファイルのアップロード、ファイルを削除済みにする、ファイルのメタデータの取得、ファイルのアーカイブ、ファイルと関連アイテムのハード(永久)削除、ファイルのグループのアクセス権の更新、ファイルアクセス権更新タスクのステータス確認、非公開ファイルの署名付きURLの取得、ファイルの移動、フォルダーの作成、フォルダーのメタデータのリスト、フォルダーの削除、IDによるフォルダーの取得
HubSpot内でファイルを管理および保存するには、HubSpotのファイルツールを使用します。HubSpotでホスティングされているファイルは、HubSpotと外部コンテンツの両方にアップロードして使用できます。エンゲージメントAPIを使用して、ファイルをレコードに添付することもできます。
HubSpotのCMSを使用してウェブサイトを構築する場合、ファイルAPIを使用してアセットをHubSpotにアップロードして保存し、その後HubSpotのCMSを通じて配信できます。
ファイルツールはHubSpot内で、またはファイルAPI経由で利用できます。以下では、ファイルAPIについてと、ファイルのアップロード方法および削除方法について説明します。ファイルAPIエンドポイントの一覧を確認するには、ページ上部にある[エンドポイント]タブをクリックしてください。
ファイルAPIの旧バージョンを使用している場合、v3には次の変更点があります。
- このAPI経由でアップロードした全てのファイルは、ファイルダッシュボードおよびファイル選択時に表示されます。非表示ファイルを作成することはできません。ただし、非公開ファイルとインデックス登録不可のファイルは引き続き作成できます。
- ファイルのリストでは、非表示のファイルや削除済みのファイルが返されません。ただし、適用できるフィルターの種類が大幅に増えました。非表示のファイルは引き続きIDを指定して取得できますが、その場合は新しいスコープ
files_ui_hidden.read
が必要になります。 - 1回のリクエストで複数のファイルをアップロードすることはできません。
- 移動や名前変更などのフォルダー更新アクションは非同期になりました。リクエストごとに、フォルダーの編集ステータスの確認に使用できるトークンが返されます。
- ファイルを作成または置換するエンドポイントを使用するには、ファイルのアクセスレベルを指定する必要があります。このアクセスレベルを以下に示します。
PUBLIC_INDEXABLE
:ファイルが一般に公開され、URLを知っている全てのユーザーがアクセスできます。このファイルは、検索エンジンによるインデックス登録が可能です。PUBLIC_NOT_INDEXABLE
:ファイルが一般に公開され、URLを知っている全てのユーザーがアクセスできます。ファイルの取得時には常に「X-Robots-Tag: noindex」ヘッダーが送信され、検索エンジンに対し、ファイルをインデックス登録しないよう通知されます。PRIVATE
:ファイルは一般公開されません。コンテンツを表示するには署名付きURLが必要です。検索エンジンはこのファイルのインデックス登録を行うことができません。
- ファイルを作成するエンドポイントでは、ファイルのアップロードオプションの一部として、重複検出レベルを指定できます。
ENTIRE_PORTAL
:アカウント内で重複するファイルを検索します。EXACT_FOLDER
:指定されたフォルダー内で重複するファイルを検索します。
NONE
:重複の検証を実行しません。REJECT
:重複が検出された場合はアップロードを拒否します。RETURN_EXISTING
:重複するファイルが検出された場合は、新しいファイルをアップロードせずに、検出された重複ファイルを返します。- 重複検出は
duplicateValidationScope
を基に機能するため、重複の検索にも影響します。 - 重複が検出された場合の処理を指示する
duplicateValidationStrategy
も必要です。
フィールド | 必須 | Description | Example |
---|---|---|---|
file
| Yes | アップロードするファイル。 |
"file": {binary data}
|
options
| Yes | ファイルのアップロードオプション。必須フィールドは、ファイルの公開設定とインデックス登録を制御する
|
"options": "{
"access": "PRIVATE",
"ttl": "P2W",
"overwrite": false,
"duplicateValidationStrategy": "NONE",
"duplicateValidationScope":
"EXACT_FOLDER"
}"
|
folderId
| No | ファイルのアップロード先とするフォルダーのID。 |
"folderId": 1234
|
folderPath
| No | ファイルのアップロード先とするフォルダーのパス。 |
"folderPath": "/folder"
|
fileName
| No | ファイルの名前。名前が指定されていない場合は、ファイルの内容に基づく名前が生成されます。 |
"fileName": "myImage"
|
charsetHunch
| No | アップロードするファイルのエンコーディングとして使用されている文字セット。指定されていない場合、ファイルから取得されます。 |
"charsetHunch": "UTF-8"
|
ファイルを削除するには、DELETE
リクエストをfiles/v3/files/{fileId}
に送信します。これにより、ファイルは削除済みになり、ファイルの内容にアクセスできなくなります。
ファイルを完全に削除するには、DELETE
リクエストをfiles/v3/files/{fileId}/gdpr-delete
に送信します。これにより、ファイルの内容とメタデータが7日以内に完全に削除されます。
GDPRを適用しない削除方法の場合、ファイルの内容は、誰もアクセスできない非公開の状態でHubSpotのサーバーに残ります。ファイルの内容を完全に削除するには、GDPR削除機能を使用します。
ファイルツールにアップロードされたファイルの詳細を表示するには、GET
リクエストをfiles/v3/files/{fileId}
に送信します。これにより、名前、高さと幅、エンコード、URLなどの詳細情報と共にファイルが返されます。
ファイルが非公開に設定されている場合、URLの結果として404エラーが返されます。ファイルの表示可能なURLを取得するには、GET
リクエストを/files/v3/files/{fileId}/signed-url
に送信します。このリクエストを送信するときには、高さと幅などの特定のプロパティーが返されるようにproperty
パラメーターを含めることができます。
フィールド | 必須 | Description | Example |
---|---|---|---|
name
| Yes | 作成するフォルダーの名前。 |
"name": "myFolder"
|
parentFolderId
| No | 既存のフォルダー内にフォルダーを作成するには、このフィールドを含め、フィールドの値としてその既存のフォルダーのIDを設定します。 |
"parentFolderId": 1234
|
parentFolderPath
| No | 既存のフォルダー内にフォルダーを作成するには、このフィールドを含めて、フィールドの値としてその既存のフォルダーのパスを設定します。 |
"folderId": 1234
|
リクエストの例
//example request
{
"name": "myNewFolder",
"parentFolderId": 12345
}
貴重なご意見をありがとうございました。