ファイル

 

概要エンドポイント

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

HubSpotのCMSを使用してウェブサイトを構築する場合、ファイルAPIを使用してアセットをHubSpotにアップロードして保存し、その後HubSpotのCMSを通じて配信できます。

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

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も必要です。

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

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

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

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

 "file": {binary data}
options
Yes

ファイルのアップロードオプション。必須フィールドは、ファイルの公開設定とインデックス登録を制御するaccessフィールドのみです。

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

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

 "options": "{ "access":  "PRIVATE", "ttl": "P2W", "overwrite": false, "duplicateValidationStrategy": "NONE", "duplicateValidationScope": "EXACT_FOLDER" }"
folderId
No

ファイルのアップロード先とするフォルダーのID。folderIdとfolderPathを同時に指定することはできません。

 "folderId": 1234
folderPath
No

ファイルのアップロード先とするフォルダーのパス。folderIdとfolderPathを同時に指定することはできません。

 "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パラメーターを含めることができます。

フォルダーを作成する

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

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

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

 "name": "myFolder"
parentFolderId
No

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

 "parentFolderId": 1234
parentFolderPath
No

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

 "folderId": 1234

リクエストの例

JSON 
//example request
{
"name": "myNewFolder",
"parentFolderId": 12345
}
参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。