マークダウンレプリゼンテーションの取得

マークダウンレプリゼンテーションを使用すると、ヘッダー、表、リスト、書式設定の指示などの構造を保持しながら、ドキュメントからテキストを抽出できます。マークダウンの変換速度は、ファイルサイズとコンテンツによって異なります。

サポートされているファイルの種類

マークダウンレプリゼンテーションは、以下のドキュメント形式に対応しています。

Microsoft Office: Word (.docx)、PowerPoint (.pptx)、Excel (.xls、.xlsx、.xlsm)
Google Workspace: Googleドキュメント (.gdoc)、Googleスライド (.gslide、.gslides)、
Googleスプレッドシート (.gsheet)
PDFファイル (.pdf)

マークダウンレプリゼンテーションの作成

この手順では、Box APIを使用してファイルのマークダウンレプリゼンテーションを生成してダウンロードする方法を説明します。最初にマークダウンレプリゼンテーションを作成するには:

値[markdown]を指定したx-rep-hintsヘッダーを渡して、する。
url_templateを呼び出してする。その際、{+asset_path}を空の文字列に置き換えます。

生成されたレプリゼンテーションは、後続のリクエストに備えてBoxによってキャッシュされます。

利用可能なレプリゼンテーションの取得

マークダウンレプリゼンテーションのヒントを指定して、ファイルの利用可能なレプリゼンテーションをリクエストします。

curl -X GET \ 
  'https://api.box.com/2.0/files/12345?fields=id%2Cname%2Crepresentations' \ 
  -H 'X-Rep-Hints: [markdown]' \ 
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

await client.files.getFileById(
  "12345",
  {
    queryParams: {
      fields: ["id", "name", "representations"],
    } satisfies GetFileByIdQueryParams,
    headers: {
      xRepHints: "[markdown]",
    } satisfies GetFileByIdHeadersInput,
  } satisfies GetFileByIdOptionalsInput,
);

client.files.get_file_by_id(
    "12345",
    fields=["id", "name", "representations"],
    x_rep_hints="[markdown]",
)

await client.Files.GetFileByIdAsync(
    fileId: "12345",
    queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"id", "name", "representations"}) },
    headers: new GetFileByIdHeaders(xRepHints: "[markdown]")
);

try await client.files.getFileById(
    fileId: "12345",
    queryParams: GetFileByIdQueryParams(fields: ["id", "name", "representations"]),
    headers: GetFileByIdHeaders(xRepHints: "[markdown]")
)

client.getFiles().getFileById(
    "12345",
    new GetFileByIdQueryParams.Builder().fields(Arrays.asList("id", "name", "representations")).build(),
    new GetFileByIdHeaders("[markdown]")
)

レスポンスの例

{
  "type": "file",
  "id": "{file_id}",
  "etag": "1",
  "name": "test.docx",
  "representations": {
    "entries": [
      {
        "representation": "markdown",
        "properties": {},
        "info": {
          "url": "https://api.box.com/2.0/internal_files/{file_id}/versions/{version_id}/representations/{representation}"
        },
        "status": {
          "state": "none"
        },
        "content": {
          "url_template": "https://dl.boxcloud.com/api/2.0/internal_files/{file_id}/versions/{version_id}/representations/{representation}/content/{+asset_path}"
        }
      }
    ]
  }
}

マークダウン生成の開始

状態がnoneの場合、マークダウンレプリゼンテーションの生成を開始するために情報URLをリクエストします。

curl -X GET \ 
  'https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown' \ 
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

await fetch(
  "https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown",
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
  },
);

requests.get(
    "https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown",
    headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
)

using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");
await httpClient.GetAsync("https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown");

var request = URLRequest(url: URL(string: "https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown")!)
request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
_ = try await URLSession.shared.data(for: request)

HttpClient httpClient = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .GET()
    .build();
httpClient.send(request, HttpResponse.BodyHandlers.discarding());

レプリゼンテーションのステータスの確認

ファイルに再度クエリを実行して、マークダウンレプリゼンテーションの現在のステータスを確認します。

curl -X GET \ 
  'https://api.box.com/2.0/files/12345?fields=id%2Cname%2Crepresentations' \ 
  -H 'X-Rep-Hints: [markdown]' \ 
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

await client.files.getFileById(
  "12345",
  {
    queryParams: {
      fields: ["id", "name", "representations"],
    } satisfies GetFileByIdQueryParams,
    headers: {
      xRepHints: "[markdown]",
    } satisfies GetFileByIdHeadersInput,
  } satisfies GetFileByIdOptionalsInput,
);

client.files.get_file_by_id(
    "12345",
    fields=["id", "name", "representations"],
    x_rep_hints="[markdown]",
)

await client.Files.GetFileByIdAsync(
    fileId: "12345",
    queryParams: new GetFileByIdQueryParams() { Fields = Array.AsReadOnly(new [] {"id", "name", "representations"}) },
    headers: new GetFileByIdHeaders(xRepHints: "[markdown]")
);

try await client.files.getFileById(
    fileId: "12345",
    queryParams: GetFileByIdQueryParams(fields: ["id", "name", "representations"]),
    headers: GetFileByIdHeaders(xRepHints: "[markdown]")
)

client.getFiles().getFileById(
    "12345",
    new GetFileByIdQueryParams.Builder().fields(Arrays.asList("id", "name", "representations")).build(),
    new GetFileByIdHeaders("[markdown]")
)

ステータスがpendingからsuccessに変わると、マークダウンファイルはダウンロード可能になります。このステータスはレプリゼンテーションが利用可能かどうかを示します。利用可能なオプションはsuccess、viewable、pending、noneです。Successはレプリゼンテーションを即座にダウンロードできることを意味するのに対し、noneはレプリゼンテーションが生成可能であることを示します。

マークダウンレプリゼンテーションのダウンロード

レプリゼンテーションの準備が整ったら、content/url_templateを使用してダウンロードします。

curl -L \ 
'https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/1415005153353/representations/markdown/content/index.md' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -o file_name.md

await fetch(
  "https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/",
  {
    headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
  },
);

requests.get(
    "https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/",
    headers={"Authorization": "Bearer YOUR_ACCESS_TOKEN"},
)

using var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "YOUR_ACCESS_TOKEN");
await httpClient.GetAsync("https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/");

var request = URLRequest(url: URL(string: "https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/")!)
request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
_ = try await URLSession.shared.data(for: request)

HttpClient httpClient = HttpClient.newBuilder()
    .followRedirects(HttpClient.Redirect.NORMAL)
    .build();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/"))
    .header("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .GET()
    .build();
httpClient.send(request, HttpResponse.BodyHandlers.ofByteArray());

はじめに

アプリケーションと統合

IDとアクセス

APIの利用

トラブルシューティング

コンテンツ

コラボレーション

メタデータと検索

イベントとWebhook

ユーザー

インテリジェントなワークフロー

電子サイン

セキュリティとコンプライアンス

マークダウンレプリゼンテーションの取得

サポートされているファイルの種類

マークダウンレプリゼンテーションの作成

利用可能なレプリゼンテーションの取得

レスポンスの例

マークダウン生成の開始

レプリゼンテーションのステータスの確認

マークダウンレプリゼンテーションのダウンロード

​サポートされているファイルの種類

​マークダウンレプリゼンテーションの作成

​利用可能なレプリゼンテーションの取得

​レスポンスの例

​マークダウン生成の開始

​レプリゼンテーションのステータスの確認

​マークダウンレプリゼンテーションのダウンロード

サポートされているファイルの種類

マークダウンレプリゼンテーションの作成

利用可能なレプリゼンテーションの取得

レスポンスの例

マークダウン生成の開始

レプリゼンテーションのステータスの確認

マークダウンレプリゼンテーションのダウンロード