> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CMS | ソースコードAPI

export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<RelatedApiLink />

<Accordion title="スコープ要件">
  <ScopesList
    scopes={[
  'content'
]}
  />
</Accordion>

## 基本機能

CMSソースコードAPIを使用すると、HubSpot[デベロッパー ファイル システム](https://developers.hubspot.jp/docs/cms/start-building/introduction/overview#developer-file-system)に格納されたファイルを操作できます。これらのファイルには、デザインマネージャーに表示されるテンプレート、モジュール、CSS、JSなどの全てのCMSアセットが含まれます。このAPIでは次の操作ができます。

* 新しいファイルをHubSpotアカウントにアップロードするか、既存のファイル対する変更をアップロードします。
* CMSアセットをアカウントからダウンロードまたは削除します。
* デザインマネージャー内の各ファイルまたは各フォルダーのメタデータを取得します。
* HubSpotのCMS上のファイルの内容（HubL構文を含む）を検証します。
* zipファイルをファイルパッケージとしてアップロードし、アカウント内に展開します。

このAPIでは、全てのCMSアセットをローカル環境で編集するとともに、作業の迅速化に役立つツールを作成できます。

## 環境とパス

ソースコードAPIエンドポイントでは、CMSデベロッパー ファイル システム内でのファイルの特定に`environment`パラメーターと`path`パラメーターを使用します。このパラメーターは通常、エンドポイントパス自体に、例えば`/cms/v3/source-code/{environment}/content/{path}`のように指定します。

`environment`パラメーターは、各ファイルの未公開バージョンまたは公開バージョンのいずれを操作するかを示します。未公開のバージョンの場合は`draft`を使用します。公開中のバージョンの場合は`published`を使用します。

<Info>
  `published`へのアップロードはデザインマネージャー上で［公開］ボタンを押すことに相当する点に注意してください。そのため、`draft`にある全ての内容が消去されます。
</Info>

`path`パラメーターは、CMSデベロッパー ファイル システムでのファイルの位置を示します。UNIXベースのオペレーティングシステムとは異なり、最上位レベルのアセットの前に`/`文字は付きません。新しいファイルをアップロードする際には、ファイルの作成先となる場所を指定する必要があります。既存のファイルを取得する、または既存のファイルに対する変更をアップロードする場合は、既存のファイルのパスに一致している必要があります。

全てのアセットタイプに、ローカルのファイル形式が使用されます。つまりアセットが、タイプによっては複数のファイルで構成されます。例えば、モジュールは実際には`.module`サフィックスが末尾に付くディレクトリーとして表されます。このため、モジュールのHTMLを取得するには、`foo.module/module.html`のようなパスを使用する必要があります。詳細については、[ローカル開発のドキュメント](https://developers.hubspot.com/docs/developer-tooling/local-development/hubspot-cli/reference)を参照してください。

## ファイルをダウンロードする

HubSpotアカウントからは、`/cms/v3/source-code/{environment}/content/{path}`エンドポイントを使用してファイルをダウンロードできます。

このためには、`application/octet-stream`コンテンツタイプを受け入れるHTTP GETリクエストを使用します。これにより、指定したパスの実際のバイナリーファイルの内容をダウンロードできます。

**例：**

* **ファイルのダウンロード：** GET `/cms/v3/source-code/published/content/my-file.js` Accept: `application/octet-stream`

フォルダーの内容全体をダウンロードすることはできません。代わりに、フォルダーのメタデータを取得し（以下を参照）、子を個別に取得する必要があります。

## ファイルとフォルダーのメタデータを取得する

開発者は`/cms/v3/source-code/{environment}/metadata/{path}`エンドポイントを使用することで、HubSpotアカウント上のファイルまたはフォルダーのメタデータ（パス、ファイル名、作成／更新時のタイムスタンプなど）を取得できます。

このためには、`application/json`コンテンツタイプを受け入れるHTTP GETリクエストを使用します。これにより、そのファイルの関連メタデータを含むJSONオブジェクトを取得できます。

フォルダーのメタデータは、`folder: true`プロパティーにより示されます。`children`配列は、フォルダー内のファイルとサブフォルダーの名前を示します。これらのファイル名をフォルダーツリーの走査に使用します。1つのフォルダーのメタデータを取得し、そのフォルダーの子と全てのサブフォルダーを再帰的に取得します。

**例：**

* **フォルダーのメタデータを取得する：** GET `/cms/v3/source-code/published/metadata/my-folder` Accept: `application/json`

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

HubSpotアカウントには、`/cms/v3/source-code/{environment}/content/{path}`エンドポイントを使用してローカルのファイルをアップロードできます。ファイルは、`multipart/form-data`コンテンツタイプを指定したHTTP PUTリクエストによってアップロードする必要があります。バイナリー ファイル データを`file`という名前のフィールドとして含める必要があります。

**例：**

* **新規ファイルをアップロードする：** PUT `/cms/v3/source-code/published/content/my-new-file.html` Content-Type: multipart/form-dataフォームデータ：`{ file: [バイナリー ファイル データ] }`
* **既存の下書きファイルを更新する：** PUT `/cms/v3/source-code/draft/content/path/to/existing-file.html` Content-Type: multipart/form-dataフォームデータ：`{ file: [バイナリー ファイル データ] }`

HubSpotでは現在、以下のCMSアセット ファイル タイプをサポートしています。

* `css`
* `js`
* `json`
* `html`
* `txt`
* `md`
* `jpg`
* `jpeg`
* `png`
* `gif`
* `map`
* `svg`
* `ttf`
* `woff`
* `woff2`

## ファイルの内容を検証する

ローカルファイルの内容は、`/cms/v3/source-code/{environment}/validate/{path}`エンドポイントを使用して検証できます。

これは、テンプレート／モジュール、またはテーマまたはモジュールのJSON内のHubLの検証に使用できます。これにより、デザインマネージャーに表示される警告とエラーが示されます。

<Info>
  無効なファイルは直接発行しようとしても拒否される点に注意してください。**公開前にまずファイルを検証することをお勧めします。**
</Info>

ファイルは、`multipart/form-data`コンテンツタイプを指定したHTTP POSTリクエストによって送信する必要があります。バイナリー ファイル データを`file`という名前のフィールドとして含める必要があります。検証にエラーがあった場合、`400`レスポンスと関連するエラーのリストが返されます。

**例：**

* **新規ファイルをアップロードする：** POST `/cms/v3/source-code/published/validate/my-file.html` Content-Type: multipart/form-dataフォームデータ：`{ file: \[バイナリー ファイル データ\] }`

## ファイルを削除する

HubSpotアカウントからは、`/cms/v3/source-code/{environment}/content/{path}`エンドポイント経由でHTTP DELETEリクエストを使用してファイルを削除できます。

`published`（公開）環境から削除すると、ファイルは完全に削除されます。`draft`（下書き）環境から削除すると、未公開の変更が消去されるだけです。公開ファイルを削除すると、使用されていたファイルが公開中のコンテンツに即座に影響を与えます。このため、ファイルに対する全ての参照を削除してから、ファイルを削除してください。

**例：**

* **ファイルを削除する：** DELETE `/cms/v3/source-code/published/content/my-file.html`

## ファイルパッケージを展開する

HubSpotアカウントには、`/cms/v3/source-code/extract/{path}`エンドポイント経由でHTTP POSTリクエストを使用してzipファイルを展開できます。

この`path`は、アカウントにアップロード済みのzipファイルである必要があります。展開プロセスは非同期で、圧縮ファイルの数とサイズに応じて最大で1分程度かかることがあります。zipの内容は、zipファイルが置かれているのと同じフォルダーに展開されます。展開が正常に完了しても、元のzipファイルは自動削除されません。

**例：**

* \*\*zipファイルをアップロードする： \*\*PUT `/cms/v3/source-code/published/content/my-package.zip` Content-Type: multipart/form-dataフォームデータ：`{ file: \[バイナリー ファイル データ\] }`

* **zipファイルを展開する：** POST `/cms/v3/source-code/extract/my-package.zip`