> ## Documentation Index
> Fetch the complete documentation index at: https://developer.box.com/llms.txt
> Use this file to discover all available pages before exploring further.

> Box APIを使用してマークダウンレプリゼンテーションを生成し、ダウンロードします。

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

export const Link = ({href, children, className, ...props}) => {
  const localizedHref = localizeLink(href);
  return <a href={localizedHref} className={className} {...props}>
      {children}
    </a>;
};

export const MultiRelatedLinks = ({sections = []}) => {
  if (!sections || sections.length === 0) {
    return null;
  }
  return <div className="space-y-8">
      {sections.map((section, index) => <RelatedLinks key={index} title={section.title} items={section.items} />)}
    </div>;
};

export const RelatedLinks = ({title, items = []}) => {
  const getBadgeClass = badge => {
    if (!badge) return "badge-default";
    const badgeType = badge.toLowerCase().replace(/\s+/g, "-");
    return `badge-${badge === "ガイド" ? "guide" : badgeType}`;
  };
  if (!items || items.length === 0) {
    return null;
  }
  return <div className="my-8">
      {}
      <h3 className="text-sm font-bold uppercase tracking-wider mb-4">{title}</h3>

      {}
      <div className="flex flex-col gap-3">
        {items.map((item, index) => <a key={index} href={item.href} className="py-2 px-3 rounded related_link hover:bg-[#f2f2f2] dark:hover:bg-[#111827] flex items-center gap-3 group no-underline hover:no-underline border-b-0">
            {}
            <span className={`px-2 py-1 rounded-full text-xs font-semibold uppercase tracking-wide flex-shrink-0 ${getBadgeClass(item.badge)}`}>
              {item.badge}
            </span>

            {}
            <span className="text-base">{item.label}</span>
          </a>)}
      </div>
    </div>;
};

<RelatedLinks
  title="必須のガイド"
  items={[
{ label: translate("List All Representations for File"), href: "/guides/representations/list-all-representations", badge: "GUIDE" },
{ label: translate("Request Desired Representation"), href: "/guides/representations/request-a-representation", badge: "GUIDE" },
{ label: translate("Download File Representation"), href: "/guides/representations/download-a-representation", badge: "GUIDE" }
]}
/>

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

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

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

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

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

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

最初にマークダウンレプリゼンテーションを作成するには:

* <Link href="/guides/representations/list-all-representations">ファイルの利用可能なレプリゼンテーションのリストを取得する。</Link>
* 値`[markdown]`を指定した`x-rep-hints`ヘッダーを渡して、<Link href="/guides/representations/request-a-representation">マークダウンレプリゼンテーションをリクエスト</Link>する。
* `url_template`を呼び出して<Link href="/guides/representations/download-a-representation">マークダウンをダウンロード</Link>する。その際、`{+asset_path}`を空の文字列に置き換えます。

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

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

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

<CodeGroup>
  ```sh cURL theme={null}
  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'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.files.getFileById(
    "12345",
    {
      queryParams: {
        fields: ["id", "name", "representations"],
      } satisfies GetFileByIdQueryParams,
      headers: {
        xRepHints: "[markdown]",
      } satisfies GetFileByIdHeadersInput,
    } satisfies GetFileByIdOptionalsInput,
  );
  ```

  ```python Python v10 theme={null}
  client.files.get_file_by_id(
      "12345",
      fields=["id", "name", "representations"],
      x_rep_hints="[markdown]",
  )
  ```

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

  ```swift Swift v10 theme={null}
  try await client.files.getFileById(
      fileId: "12345",
      queryParams: GetFileByIdQueryParams(fields: ["id", "name", "representations"]),
      headers: GetFileByIdHeaders(xRepHints: "[markdown]")
  )
  ```

  ```java Java v10 theme={null}
  client.getFiles().getFileById(
      "12345",
      new GetFileByIdQueryParams.Builder().fields(Arrays.asList("id", "name", "representations")).build(),
      new GetFileByIdHeaders("[markdown]")
  )
  ```
</CodeGroup>

## レスポンスの例

```json theme={null}
{
  "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をリクエストします。

<CodeGroup>
  ```sh cURL theme={null}
  curl -X GET \ 
    'https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown' \ 
    -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await fetch(
    "https://api.box.com/2.0/internal_files/12345/versions/2200612360399/representations/markdown",
    {
      headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
    },
  );
  ```

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

  ```cs .NET v10 theme={null}
  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");
  ```

  ```swift Swift v10 theme={null}
  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)
  ```

  ```java Java v10 theme={null}
  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());
  ```
</CodeGroup>

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

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

<CodeGroup>
  ```sh cURL theme={null}
  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'
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await client.files.getFileById(
    "12345",
    {
      queryParams: {
        fields: ["id", "name", "representations"],
      } satisfies GetFileByIdQueryParams,
      headers: {
        xRepHints: "[markdown]",
      } satisfies GetFileByIdHeadersInput,
    } satisfies GetFileByIdOptionalsInput,
  );
  ```

  ```python Python v10 theme={null}
  client.files.get_file_by_id(
      "12345",
      fields=["id", "name", "representations"],
      x_rep_hints="[markdown]",
  )
  ```

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

  ```swift Swift v10 theme={null}
  try await client.files.getFileById(
      fileId: "12345",
      queryParams: GetFileByIdQueryParams(fields: ["id", "name", "representations"]),
      headers: GetFileByIdHeaders(xRepHints: "[markdown]")
  )
  ```

  ```java Java v10 theme={null}
  client.getFiles().getFileById(
      "12345",
      new GetFileByIdQueryParams.Builder().fields(Arrays.asList("id", "name", "representations")).build(),
      new GetFileByIdHeaders("[markdown]")
  )
  ```
</CodeGroup>

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

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

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

<CodeGroup>
  ```sh cURL theme={null}
  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
  ```

  ```typescript Node/TypeScript v10 theme={null}
  await fetch(
    "https://dl.boxcloud.com/api/2.0/internal_files/12345/versions/2200612360399/representations/markdown/content/",
    {
      headers: { Authorization: "Bearer YOUR_ACCESS_TOKEN" },
    },
  );
  ```

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

  ```cs .NET v10 theme={null}
  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/");
  ```

  ```swift Swift v10 theme={null}
  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)
  ```

  ```java Java v10 theme={null}
  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());
  ```
</CodeGroup>

<RelatedLinks
  title="関連するAPI"
  items={[
{ label: translate("Get file information"), href: "/reference/get-files-id", badge: "GET" }
]}
/>

<RelatedLinks
  title="関連するガイド"
  items={[
{ label: translate("Supported File Types"), href: "/guides/representations/supported-file-types", badge: "GUIDE" }
]}
/>