ファイルオブジェクト

📘
Notion API は、Notion へのファイルのアップロードをまだサポートしていません。

ファイルオブジェクトには、Notion にアップロードされたファイルに関するデータ、または Notion でリンクされた外部ファイルに関するデータが含まれます。

Notion にアップロードされたファイルに対応するファイルオブジェクト

{
  "type": "file",
  "file": {
    "url": "https://s3.us-west-2.amazonaws.com/secure.notion-static.com/7b8b0713-dbd4-4962-b38b-955b6c49a573/My_test_image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221024%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221024T205211Z&X-Amz-Expires=3600&X-Amz-Signature=208aa971577ff05e75e68354e8a9488697288ff3fb3879c2d599433a7625bf90&X-Amz-SignedHeaders=host&x-id=GetObject",
    "expiry_time": "2022-10-24T22:49:22.765Z"
  }
}

Notion でリンクされている外部ファイルに対応するファイルオブジェクト

{
  "type": "external",
  "external": {
    "url": "https://images.unsplash.com/photo-1525310072745-f49212b5ac6d?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1065&q=80"
  }
}

ページ、埋め込み、画像、ビデオ、ファイル、pdf、およびブックマークのブロックタイプには、すべてファイルオブジェクトが含まれます。アイコンおよびカバーページオブジェクトの値には、ファイルオブジェクトも含まれます。

各ファイルオブジェクトには、次のフィールドが含まれます。

フィールド	タイプ	説明	例の値
`type`	`string` (列挙型)	ファイルオブジェクトのタイプ。可能なタイプ値は次のとおりです。 `"external"` `"file"`	`"external"`
`external`		`file`	`object`

Notionホストファイル

Notion がホストするすべてのファイルには"file"のtypeが含まれています。対応fileの特定のオブジェクトには、次のフィールドが含まれています。

フィールド	タイプ	説明	例の値
`url`	`string`	ファイルへの認証済み S3 URL。 URL は 1 時間有効です。リンクの有効期限が切れた場合は、API リクエストを送信して、更新された URL を取得できます。	`"https://s3.us-west-2.amazonaws.com/secure.notion-static.com/9bc6c6e0-32b8-4d55-8c12-3ae931f43a01/brocolli.jpeg?..."`
`expiry_time`	`string` ( ISO 8601日時)	ISO 8601 日時文字列としてフォーマットされた、リンクの有効期限が切れる日時。	`"2020-03-17T19:10:04.968Z"`

ブロックの子の取得エンドポイントを介して、Notion がホストするファイルへのリンクを取得できます。

例: GET /children を使用して、Notion がホストするファイルへの URL を取得する

次の例では、目的のファイルを含むページの ID を block_id パスパラメータとして渡します。

リクエスト

cURL

curl 'https://api.notion.com/v1/blocks/13d6da822f9343fa8ec14c89b8184d5a/children?page_size=100' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Notion-Version: 2022-02-22"

レスポンス

JSON

{
    "object": "list",
    "results": [
        {
            "object": "block",
            "id": "47a920e4-346c-4df8-ae78-905ce10adcb8",
            "parent": {
                "type": "page_id",
                "page_id": "13d6da82-2f93-43fa-8ec1-4c89b8184d5a"
            },
            "created_time": "2022-12-15T00:18:00.000Z",
            "last_edited_time": "2022-12-15T00:18:00.000Z",
            "created_by": {
                "object": "user",
                "id": "c2f20311-9e54-4d11-8c79-7398424ae41e"
            },
            "last_edited_by": {
                "object": "user",
                "id": "c2f20311-9e54-4d11-8c79-7398424ae41e"
            },
            "has_children": false,
            "archived": false,
            "type": "paragraph",
            "paragraph": {
                "rich_text": [],
                "color": "default"
            }
        },
        {
            "object": "block",
            "id": "3c29dedf-00a5-4915-b137-120c61f5e5d8",
            "parent": {
                "type": "page_id",
                "page_id": "13d6da82-2f93-43fa-8ec1-4c89b8184d5a"
            },
            "created_time": "2022-12-15T00:18:00.000Z",
            "last_edited_time": "2022-12-15T00:18:00.000Z",
            "created_by": {
                "object": "user",
                "id": "c2f20311-9e54-4d11-8c79-7398424ae41e"
            },
            "last_edited_by": {
                "object": "user",
                "id": "c2f20311-9e54-4d11-8c79-7398424ae41e"
            },
            "has_children": false,
            "archived": false,
            "type": "file",
            "file": {
                "caption": [],
                "type": "file",
                "file": {
                    "url": "https://s3.us-west-2.amazonaws.com/secure.notion-static.com/fa6c03f0-e608-45d0-9327-4cd7a5e56e71/TestFile.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAT73L2G45EIPT3X45%2F20221215%2Fus-west-2%2Fs3%2Faws4_request&X-Amz-Date=20221215T002012Z&X-Amz-Expires=3600&X-Amz-Signature=bf13ca59f618077852298cb92aedc4dd1becdc961c31d73cbc030ef93f2853c4&X-Amz-SignedHeaders=host&x-id=GetObject",
                    "expiry_time": "2022-12-15T01:20:12.928Z"
                }
            }
        },
    ],
    "next_cursor": null,
    "has_more": false,
    "type": "block",
    "block": {}
}

外部ファイル

外部ファイルとは、Notion によってホストされていない、Notion 内でリンクされている URL です。すべての外部ファイルのタイプは. 対応する特定のオブジェクトには、次のフィールドが含まれています。"external"``file

フィールド	タイプ	説明	例の値
`url`	`string`	外部でホストされているコンテンツへのリンク。	`"https://website.domain/files/doc.txt"`

Notion API は、外部ファイルへのリンクの追加、取得、更新をサポートしています。

例: PATCH /children を使用して外部ファイルに URL を追加する

Append block childrenエンドポイントを使用して、外部ファイルを Notion に追加します。外部ファイルに関する情報の詳細を示すブロック型オブジェクトを本文に渡します。

次のリクエスト例では、PDF を Notion ページに埋め込みます。ターゲットページの ID をblock_idパスパラメーターとして渡し、ファイルに関する情報を要求本文に追加します。

リクエスト

cURL

curl -X PATCH 'https://api.notion.com/v1/blocks/13d6da822f9343fa8ec14c89b8184d5a/children' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-02-22" \
  --data '{
  "children": [
    {
      "object": "block",
      "type": "pdf",
      "pdf": {
        "type": "external",
        "external": {
          "url": "https://www.yourwebsite.dev/files/TestFile.pdf"
        }
      }
    }
  ]
}'

レスポンス

JSON

{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "af1459f2-d2c5-4ca6-9f05-8038e6eb167f",
      "parent": {
        "type": "page_id",
        "page_id": "13d6da82-2f93-43fa-8ec1-4c89b8184d5a"
      },
      "created_time": "2022-12-15T01:14:00.000Z",
      "last_edited_time": "2022-12-15T01:14:00.000Z",
      "created_by": {
        "object": "user",
        "id": "9188c6a5-7381-452f-b3dc-d4865aa89bdf"
      },
      "last_edited_by": {
        "object": "user",
        "id": "9188c6a5-7381-452f-b3dc-d4865aa89bdf"
      },
      "has_children": false,
      "archived": false,
      "type": "pdf",
      "pdf": {
        "caption": [],
        "type": "external",
        "external": {
          "url": "https://www.yourwebsite.dev/files/TestFile.pdf"
        }
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "block",
  "block": {}
}

例: GET /children を使用して外部ファイルへのリンクを取得する

ファイルオブジェクトを取得するには、ファイルの親ブロックでブロックの子の取得エンドポイントを使用します。ファイル自体は、タイプの独自のfileブロックに含まれています。

次の例では、目的のファイルを含むページの ID をblock_idパスパラメーターとして渡します。

リクエスト

cURL

curl 'https://api.notion.com/v1/blocks/af1459f2-d2c5-4ca6-9f05-8038e6eb167f/children?page_size=100' \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Notion-Version: 2022-02-22"

レスポンス

JSON

{
  "object": "list",
  "results": [
    {
      "object": "block",
      "id": "47a920e4-346c-4df8-ae78-905ce10adcb8",
      "parent": {
        "type": "page_id",
        "page_id": "13d6da82-2f93-43fa-8ec1-4c89b8184d5a"
      },
      "created_time": "2022-12-15T00:18:00.000Z",
      "last_edited_time": "2022-12-15T00:18:00.000Z",
      "created_by": {
        "object": "user",
        "id": "c2f20311-9e54-4d11-8c79-7398424ae41e"
      },
      "last_edited_by": {
        "object": "user",
        "id": "c2f20311-9e54-4d11-8c79-7398424ae41e"
      },
      "has_children": false,
      "archived": false,
      "type": "paragraph",
      "paragraph": {
        "rich_text": [],
        "color": "default"
      }
    },
    {
      "object": "block",
      "id": "af1459f2-d2c5-4ca6-9f05-8038e6eb167f",
      "parent": {
        "type": "page_id",
        "page_id": "13d6da82-2f93-43fa-8ec1-4c89b8184d5a"
      },
      "created_time": "2022-12-15T01:14:00.000Z",
      "last_edited_time": "2022-12-15T01:14:00.000Z",
      "created_by": {
        "object": "user",
        "id": "9188c6a5-7381-452f-b3dc-d4865aa89bdf"
      },
      "last_edited_by": {
        "object": "user",
        "id": "9188c6a5-7381-452f-b3dc-d4865aa89bdf"
      },
      "has_children": false,
      "archived": false,
      "type": "pdf",
      "pdf": {
        "caption": [],
        "type": "external",
        "external": {
          "url": "https://www.yourwebsite.dev/files/TestFile.pdf"
        }
      }
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "block",
  "block": {}
}

例: PATCH /blocks/{block_id} を使用して外部ファイルへのリンクを更新する

Update a blockエンドポイントを使用して、Notion の外部ファイルへのリンクを更新します。

リクエストの本文は、ファイルの Notionブロックタイプによって異なります。一般的なファイルブロックタイプには、image、pdf 、およびvideoが含まれています。

📘
ファイルの Notion ブロックタイプがわからない場合は、親ブロック ID を使用してブロックの子の取得エンドポイントにリクエストを送信し、対応する子ブロックを見つけます。

次の例では、pdfブロックタイプの外部ファイルを更新します。ブロックの ID をblock_idパスパラメータとして渡し、新しいファイルに関する情報をリクエスト本文で渡します。

リクエスト

cURL

curl https://api.notion.com/v1/blocks/af1459f2-d2c5-4ca6-9f05-8038e6eb167f \
  -H 'Authorization: Bearer '"$NOTION_API_KEY"'' \
  -H "Content-Type: application/json" \
  -H "Notion-Version: 2022-02-22" \
  -X PATCH \
  --data '{
      "pdf": { 
            "external": {
                "url": "https://www.yourwebsite.dev/files/NewFile.pdf"
            }
      }
    }'

レスポンス

JSON

{
  "object": "block",
  "id": "af1459f2-d2c5-4ca6-9f05-8038e6eb167f",
  "parent": {
    "type": "page_id",
    "page_id": "13d6da82-2f93-43fa-8ec1-4c89b8184d5a"
  },
  "created_time": "2022-12-15T01:14:00.000Z",
  "last_edited_time": "2022-12-16T21:23:00.000Z",
  "created_by": {
    "object": "user",
    "id": "9188c6a5-7381-452f-b3dc-d4865aa89bdf"
  },
  "last_edited_by": {
    "object": "user",
    "id": "9188c6a5-7381-452f-b3dc-d4865aa89bdf"
  },
  "has_children": false,
  "archived": false,
  "type": "pdf",
  "pdf": {
    "caption": [],
    "type": "external",
    "external": {
      "url": "https://www.yourwebsite.dev/files/NewFile.pdf"
    }
  }
}

📘
icon、cover 、またはfilesページプロパティ値などのファイルオブジェクトから作成されたページまたはデータベースプロパティ値を変更するには、更新ページまたは更新データベースエンドポイントを使用します。

ファイルオブジェクト

ファイル オブジェクト#

📘#

Notionホスト ファイル#

例: GET /children を使用して、Notion がホストするファイルへの URL を取得する#

リクエスト#

レスポンス#

外部ファイル#

例: PATCH /children を使用して外部ファイルに URL を追加する#

リクエスト#

レスポンス#

例: GET /children を使用して外部ファイルへのリンクを取得する#

リクエスト#

レスポンス#

例: PATCH /blocks/{block_id} を使用して外部ファイルへのリンクを更新する#

📘#

リクエスト#

レスポンス#

📘#

ファイルオブジェクト

📘

Notionホストファイル

例: GET /children を使用して、Notion がホストするファイルへの URL を取得する

リクエスト

レスポンス

外部ファイル

例: PATCH /children を使用して外部ファイルに URL を追加する

リクエスト

レスポンス

例: GET /children を使用して外部ファイルへのリンクを取得する

リクエスト

レスポンス

例: PATCH /blocks/{block_id} を使用して外部ファイルへのリンクを更新する

📘

リクエスト

レスポンス

📘