ファイルマネージャー

概要エンドポイント

HubSpot内でファイルを管理および保存するには、HubSpotのファイルツールを使用します。HubSpotでホスティングされているファイルは、HubSpotと外部コンテンツの両方にアップロードして使用できます。エンゲージメントAPIを使用して、ファイルをレコードに添付することもできます。

HubSpotのCMSを使用してウェブサイトを構築する場合、ファイルAPIを使用してアセットをHubSpotにアップロードして保存できます。これらのファイルは、HubSpot CMSを介して提供および共有することができます。

ファイルツールはHubSpot内で、またはファイルAPI経由で利用できます。以下では、ファイルAPIについてと、ファイルのアップロード方法および削除方法について説明します。ファイルAPIエンドポイントの一覧を確認するには、ページ上部にある［エンドポイント］タブをクリックしてください。

ファイルをアップロードする

ファイルをアップロードするには、以下のフィールドを指定したmultipart/form-data POSTリクエストをfiles/v3/filesに送信します。アップロード時に特定のフォルダーIDは必須ではありませんが、ファイルのアップロード先はルートディレクトリーではなくフォルダーにすることが推奨されます。アップロード時のフォルダーが必要かどうかは、今後変更になる可能性があります。 

Use this table to describe parameters / fields
フィールドDescription
ファイル

アップロードするファイル（必須）。

options

ファイルの公開設定とインデックス登録を制御するJSONオブジェクトで、2つのフィールドが含まれています。必須のaccessと、ファイルが自動的に削除されるまでの期間を指定するttlです。

ttlフィールドを使用する場合：

  • 設定できる最短期間は1日です。
  • 設定できる最長期間は1年です。
  • 設定された期間が経過すると、ファイルは完全に削除されます。削除された後、ファイルを回復または復元することはできません。

folderId

ファイルのアップロード先とするフォルダーのID。リクエストには、このフィールドまたはfolderPathのいずれかを指定する必要があります（両方を指定することはできません）。

folderPath

ファイルのアップロード先とするフォルダーのパス。リクエストには、このフィールドまたはfolderIdのいずれかを指定する必要があります（両方を指定することはできません）。

fileName

ファイルの名前。名前が指定されていない場合は、ファイルの内容に基づく名前が生成されます。

charsetHunch

アップロードするファイルのエンコーディングとして使用されている文字セット。指定されていない場合、ファイルから取得されます。

例えば、次の条件を満たすファイルをHubSpotアカウントにアップロードする場合：

  • ファイル名：cat.png
  • HubSpotファイルマネージャーの移動先フォルダー：/library/cat_archive
  • HubSpotでのファイルのアクセシビリティー：非公開でアクセス可能

次のヘッダーとリクエスト本文は、リクエストの一部である必要があります。

curl --request POST \ --url https://api.hubapi.com/files/v3/files?=' \ --header 'Authorization: Bearer pat-na1-00000000-0000-0000-0000-000000000000' \ --header 'Content-type: multipart/form-data' \ --form file=@/Users/person/Downloads/cat.png \ --form 'options={"access": "PRIVATE"}' \ --form folderPath=/library/cat_archive
結果のレスポンスには、アップロードされたファイルのidとparentFolderIdが含まれます。これを使用して、GETリクエストを介してファイルを取得できます。
// 201 Response from successful file upload { "id": "122692044085", "createdAt": "2023-06-28T17:56:45.393Z", "updatedAt": "2023-06-28T17:56:45.393Z", "archived": false, "parentFolderId": "122692510820", "name": "cat", "path": "/library/cat_archive/cat.png", "size": 24574, "height": 219, "width": 225, "encoding": "png", "type": "IMG", "extension": "png", "defaultHostingUrl": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png", "url": "https://12345.fs1.hubspotusercontent-na1.net/hubfs/12345/library/cat_archive/cat.png", "isUsableInContent": true, "access": "PRIVATE" }

ファイルのアップロードステータスを確認する

files/v3/files/import-from-url/asyncへのPOSTリクエストを使用して、ファイルをURLからファイルマネージャーにインポートする場合は、ファイルのアップロードステータスを確認できます。

これを行うには、files/v3/files/import-from-url/async/tasks/{taskId}/statusへのGETリクエストを使用します。

このリクエストを送信すると、次のいずれかの返信が届きます。  

  • PENDING：ファイルはアップロード待ちのキューにあります。インポートプロセスはまだ開始されていません。 
  • PROCESSING：ファイルはアップロード中です。
  • CANCELED：アップロードはキャンセルされ、ファイルはアップロードされません。ファイルをHubSpotアカウントにインポートするには、ファイルを再度アップロードする必要があります。  
  • COMPLETE：ファイルがファイルツールに正常にアップロードされました。アップロードされたファイルがファイルツールに表示されます。  

ファイルの詳細を表示する

ファイルツールにアップロードされたファイルの詳細を確認するには、GETリクエストをfiles/v3/files/{fileId}に送信します。これにより、名前、高さと幅、エンコード、URLなどの詳細情報と共にファイルが返されます。

例えば、ファイルの詳細を取得するには、次のようにします。  

ファイルが非公開に設定されている場合、URLの結果として404エラーが返されます。ファイルの表示可能なURLを取得するには、GETリクエストを/files/v3/files/{fileId}/signed-urlに送信します。このリクエストを送信するときには、高さと幅などの特定のプロパティーが返されるようにpropertyパラメーターを含めることができます。

ファイルを削除する

ファイルを削除するには、DELETEリクエストをfiles/v3/files/{fileId}に送信します。これにより、ファイルは削除済みになり、ファイルの内容にアクセスできなくなります。

ファイルを完全に削除するには、DELETEリクエストをfiles/v3/files/{fileId}/gdpr-deleteに送信します。これにより、ファイルの内容とメタデータが7日以内に完全に削除されます。 

GDPRを適用しない削除方法の場合、ファイルの内容は、誰もアクセスできない非公開の状態でHubSpotのサーバーに残ります。ファイルの内容を完全に削除するには、GDPR削除機能を使用します。 

フォルダーを作成する

フォルダーを作成するには、POSTリクエストをfiles/v3/foldersに送信します。このリクエストには、以下のフィールドを含めることができます。 

Use this table to describe parameters / fields
フィールド必須Description
name
Yes

作成するフォルダーの名前。

parentFolderId
No

既存のフォルダー内にフォルダーを作成するには、このフィールドを含め、フィールドの値としてその既存のフォルダーのIDを設定します。parentFolderIdとparentFolderPathを同時に設定することはできません。

parentFolderPath
No

既存のフォルダー内にフォルダーを作成するには、このフィールドを含めて、フィールドの値としてその既存のフォルダーのパスを設定します。parentFolderIdとparentFolderPathを同時に設定することはできません。
JSON 
//Example request body of POST request to /files/v3/folders
{
  "name": "myNewFolder",
  "parentFolderId": 12345
}

v3での変更点

ファイル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も必要です。
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。