1. アップロードAPI

アップロードAPI (V2)

日本語翻訳に関する免責事項

このページの翻訳はAIによって自動的に行われました。可能な限り正確な翻訳を心掛けていますが、原文と異なる表現や解釈が含まれる場合があります。正確で公式な情報については、必ず英語の原文をご参照ください。

アップロードAPIを使用すると、Sitecore Content Hub Web UI以外のクライアントからコンテンツをアップロードできます。

アップロードAPIは、次のエンドポイントを公開します。

  • api/v2.0/upload - アップロードURLをリクエストします。

  • api/v2.0/upload/process - 要求を実行します。

  • api/v2.0/upload/finalize - アップロードを確定します。

メモ

10 MBを超えるファイルをアップロードするには、「 大きなファイルのアップロード」を参照してください。アップロードURLを使用できる期間を変更するには、「 アップロードURLの有効期間を変更する」を参照してください。

アップロード構成

アップロード設定は、アップロードのタイプが許可されているadministratorまたはsuperuserによって定義されるコンテキストを記述します。アップロード構成は、許可されるファイル拡張子、最大ファイル・サイズ、アセットを作成するリポジトリーとステータスなどをシステムに指示します。

手記

maximum allowed file sizeパラメータは、アップロードできるファイルのサイズを4.7 TBのAzure BLOBの上限で制限します。

必要なパラメータは、アップロード設定自体によって異なります。たとえば、ロゴをアップロードする場合は、アップロードロゴをリンクするテーマを示すために、themeという名前のパラメーターを含める必要があります。

サポートされているアクション

ファイルに対して実行できるアクションは、次のとおりです。

アクション

形容

NewAsset

新しいアセットを作成し、アップロードしたファイルを新しく作成したアセットのメインファイルとして設定します。

NewMainFile

メインファイルを、既存のアセットのアップロードされたファイルで変更します。更新する必要があるアセットを指定するには、AssetIdアクション パラメーターが必要です。

NewAlternativeFile

既存のアセットのアップロードされたファイルで代替ファイルを変更します。更新する必要があるアセットを指定するには、AssetIdアクション パラメーターが必要です。

Import

アップロードされたファイルをインポートと見なし、そのファイルのインポート ジョブを実行します。

既存の構成は4つあります。

アセットアップロード構成

このサンプルペイロードは、アセットをアップロードします。

{
    "file_name": "<FILENAME>",
    "file_size": <FILE_SIZE>,
    "action": {
        "name": "NewAsset"
    },
    "upload_configuration": {
        "name": "upload_configuration_name"
    }
}

リクエスト例:

{
    "file_name": "asset.jpg",
    "file_size": 12345,
    "action": {
        "name": "NewAsset"
    },
    "upload_configuration": {
        "name": "AssetUploadConfiguration"
    }
}

このサンプルペイロードは、アセットの新しいバージョンをアップロードします。

{
    "file_name": "<FILENAME>",
    "file_size": <FILE_SIZE>,
    "action": {
        "name": "NewMainFile",
        "parameters": {
            "AssetId": "{the asset id}"
        }
    },
    "upload_configuration": {
        "name": "upload_configuration_name"      
    }
}

リクエスト例:

{
    "file_name": "asset.jpg",
    "file_size": 12345,
    "action": {
        "name": "NewMainFile",
        "parameters": {
            "AssetId": "40588"
        }
    },
    "upload_configuration": {
        "name": "AssetUploadConfiguration"      
    }
}

このサンプルペイロードは、アセットの代替サムネイルをアップロードします。

{
    "file_name": "<FILENAME>",
    "file_size": <FILE_SIZE>,
    "action": {
        "name": "NewAlternativeFile",
        "parameters": {
            "AssetId": "{the asset id}"
        }
    },
    "upload_configuration": {
        "name": "upload_configuration_name"      
    }
}

リクエスト例:

{
    "file_name": "asset.jpg",
    "file_size": 12345,
    "action": {
        "name": "NewAlternativeFile",
        "parameters": {
            "AssetId": "40588"
        }
    },
    "upload_configuration": {
        "name": "AssetUploadConfiguration"      
    }
}

ImportPackageConfiguration (インポートパッケージ構成)

このサンプルペイロードはパッケージをインポートします。

{
  "file_name": "<FILENAME>",
  "file_size": <FILE_SIZE>,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Package"
    }
  },
  "upload_configuration": {
    "name": "ImportPackageConfiguration"
  }
}

リクエスト例:

{
  "file_name": "package.zip",
  "file_size": 12345,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Package"
    }
  },
  "upload_configuration": {
    "name": "ImportPackageConfiguration"
  }
}

ImportLocalizationsConfiguration (英語)

このサンプルペイロードは、ローカライゼーションファイルをインポートします。

{
  "file_name": "<FILENAME>",
  "file_size": <FILE_SIZE>,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Localization"
    }
  },
  "upload_configuration": {
    "name": "ImportLocalizationsConfiguration"
  }
}

リクエスト例:

{
  "file_name": "excel.xlsx",
  "file_size": 12345,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Localization"
    }
  },
  "upload_configuration": {
    "name": "ImportLocalizationsConfiguration"
  }
}

ImportDataConfiguration (インポートデータ構成)

このサンプルペイロードは、Excelファイルからデータをインポートします。

{
  "file_name": "<FILENAME>",
  "file_size": <FILE_SIZE>,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Data"
    }
  },
  "upload_configuration": {
    "name": "ImportDataConfiguration"
  }
}

リクエスト例:

{
  "file_name": "excel.xlsx",
  "file_size": 12345,
  "action": {
    "name": "Import",
    "parameters": {
      "Type": "Data"
    }
  },
  "upload_configuration": {
    "name": "ImportDataConfiguration"
  }
}

アップロード プロセス

アップロード プロセスは、次の3つの手順で構成されます。

アップロードをリクエストする

アップロードURLを取得するには、次のパラメーターを使用してエンドポイントapi/v2.0/uploadPOST要求を送信します。

  • file_name - アップロードするファイルのname

  • file_size - アップロードするファイルのsize

  • upload_configuration - 設定のアップロード。

  • action - ファイルに対して実行するアクション。

{
   "file_name":"<FILENAME>",
   "file_size":"<FILE_SIZE>",
   "upload_configuration":{
      "name":"<UPLOAD_CONFIGURATIION_NAME>",
      "parameters":{
         ...
      }
   },
   "action":{
      "name":"<ACTION_NAME>",
      "parameters":{
         ...
      }
   }
}

正常な応答は、アップロードの実行ステップで使用されるアップロードURLをLocationヘッダーに返します。このアップロードURLは、キー、名前、有効期限、および署名とともに返されます (次の例と同様/api/v2.0/upload/process?key=local-64215f47c&name=Upload_c3de2f26-8b22.jpg&expires=2020-11-20T17:00:53.1850293+00:00&signature=bQybo8zZb-Q)。

デフォルトでは、アップロードURLは5分間有効です。ただし、目的のM.UploadConfigurationエンティティのConfigurationSettingsプロパティにupload_url_lifetime_in_minutesを追加することで、時間を最大1440分 (24時間) に増やすことができます。アップロード要求に関連するすべてのチャンクのアップロードは、リンクの有効期限が切れる前に完了する必要があります。

応答は、次の情報を含むJSON本文も返します。

  • upload_identifier - アップロードジョブのidentifier

  • file_identifier - システム内のファイルidentifier

{
  "upload_identifier": "<UPLOAD_ID>",
  "file_identifier": "<FILE_ID>"
}

アップロードを実行します

アップロードのリクエスト手順のLocationヘッダーURLを使用して、アップロードするファイルをform-dataとして添付したPOSTリクエストを作成します。

次の例は、ファイルのアップロードを示しています。

curl https://<HOSTNAME>/api/v2.0/upload/process?key=local-64215f47c&name=Upload_c3de2f26-8b22.jpg&expires=2020-11-20T17:00:53.1850293+00:00&signature=bQybo8zZb-Q \
 -H "Authorization: <BEARER_TOKEN>" \
 -H "Content-Type: multipart/form-data" \
 -F "[email protected]"

アップロードを確定する

アップロードを完了するには、アップロードの要求ステップで受信したJSON応答本文を使用して、エンドポイントapi/v2.0/upload/finalizePOST要求を送信します。

  • upload_identifier - アップロードジョブのidentifier

  • file_identifier - システム内のファイルidentifier

{
  "upload_identifier": "<UPLOAD_ID>",
  "file_identifier": "<FILE_ID>"
}

成功した応答の構造は次のとおりです。

{
    "success": <Boolean>,
    "message": <optional text message>,
    "asset_id": <ASSET_ID>,
    "asset_identifier": <assetIdentifier>
}

レスポンスには、次のものが含まれます。

  • success - アップロードのステータス

  • message - オプションのエラーまたは応答メッセージ

  • asset_id - 資産を識別する数値

  • asset_identifier - アセットの大文字と小文字を区別する文字列識別子

次のPowershell 7の例は、アップロード スクリプトの構成方法を示しています。

$authToken = "Bearer xyz"
$hostName = "https://url.sitecorecontenthub.cloud"

$fileName = "test.jpg"
$filePath = "test.jpg"
$fileSize = 2492578

# create request
$createAssetBody = @{
    file_name = $fileName
    file_size = $fileSize
    upload_configuration = @{
        name = "AssetUploadConfiguration"
    }
    action = @{
        name = "NewAsset"
    }
} | ConvertTo-Json

$createUrl = $hostName + "/api/v2.0/upload"

$createResponse = Invoke-WebRequest -Uri $createUrl -Method 'POST' -Body $createAssetBody -H @{"Authorization" = $authToken; "Content-Type" = "application/json"}

# upload request

$uploadUrl = $createResponse.Headers.Location[0]

$fileStream = [System.IO.FileStream]::new($filePath, [System.IO.FileMode]::Open)
$fileHeader = [System.Net.Http.Headers.ContentDispositionHeaderValue]::new('form-data')
$fileHeader.Name = $fileName
$fileHeader.FileName = Split-Path -leaf $filePath
$fileContent = [System.Net.Http.StreamContent]::new($fileStream)
$fileContent.Headers.ContentDisposition = $fileHeader
$fileContent.Headers.ContentType = [System.Net.Http.Headers.MediaTypeHeaderValue]::Parse("text/plain")

$multipartContent = [System.Net.Http.MultipartFormDataContent]::new()
$multipartContent.Add($fileContent)

Invoke-WebRequest -Body $multipartContent -Method 'POST' -Uri $uploadUrl -Headers @{"Authorization" = $authToken}

$fileStream.Close()

# finalize request

$finalizeUrl = $hostName + "/api/v2.0/upload/finalize"

Invoke-WebRequest -Uri $finalizeUrl -Method 'POST' -Body $createResponse.Content -H @{"Authorization" = $authToken; "Content-Type" = "application/json"}
この記事を改善するための提案がある場合は、 お知らせください!