4.1 KiB
取得存取權杖
要開始使用 API，您需要取得與將使用API的帳戶相關聯的存取權杖。 本文件將介紹取得存取權杖的步驟，然後說明如何使用基本 API。
基本上，API需要存取權杖進行請求。 存取權杖是與用戶關聯的身份驗證資料，用於識別使用API的用戶，同時管理每個存取權杖具有什麼樣的操作權限。
:::tip 使用者和與該使用者關聯的存取權杖之間存在一對多關係，並且可以向使用者發行多個存取權杖。 :::
你可以輕鬆地獲得自己的存取權杖，也可以獲取使用你的應用程序的不特定用戶的存取權杖。
- 如果是前者：閱讀「手動發行您自己的存取權杖」
- 如果是後者：閱讀「請求應用程式使用者發行存取權杖」
手動發行您自己的存取權杖
您可以在 Misskey Web 的「設定 > API」中發行自己的存取權杖。
:::danger 請不要與他人分享您的存取權杖。 :::
請求應用程式使用者發行存取權杖
若要為使用應用程式的使用者（以下簡稱「使用者」）取得存取權杖，請依照下列步驟請求核發。
:::tip
下面描述的方法稱為 MiAuth，它無需創建應用程式即可立即發行存取權杖。
還有一種獲取存取權杖的方法是使用應用程式建立方法（舊方法）。 :::
步驟1
產生 UUID。從現在起，這將被稱為工作階段ID。
:::danger 此工作階段 ID 應每次生成，不應重複使用。 :::
步驟2
在使用者瀏覽器中顯示應用程式授權表單。授權表格可透過以下格式的網址開啟：
https://{host}/miauth/{session}
需要變更的部份
- 將
{host}替換為使用者伺服器的主機。主機通常由使用者輸入。 - 將
{session}替換為工作階段 ID。
您也可以在網址中設定多個選項作為查詢參數：
| 名稱 | 說明 |
|---|---|
name |
應用程式名稱。 |
icon |
應用程式的圖標圖像網址。 |
callback |
驗證後重導向的網址。 重導向時，工作階段 ID 會附加到查詢參數 session。 |
permission |
應用程式所需的權限。 列舉所請求的授權，以半形逗號 , 分隔。可以在此處查看權限清單。 |
:::tip{label='例'}
https://misskey.io/miauth/c1f6d42b-468b-4fd2-8274-e58abdedef6f?name=MyApp&callback=https%3A%2F%2Fmyapp.example.com%2Fcallback&permission=write:notes,write:following,read:drive
:::
步驟3
使用者授予應用程式存取權限後，向下列格式的網址傳送 POST 請求，將傳回一個包含存取權杖的 JSON 作為回應。
https://{host}/api/miauth/{session}/check
需要變更的部份
- 將
{host}替換為使用者伺服器的主機。 - 將
{session}替換為工作階段 ID。
回應中包含的屬性有：
| 名稱 | 說明 |
|---|---|
token |
使用者的存取權杖。 |
user |
使用者資料。 |
使用API
取得存取權杖後，就可以透過向各種端點發出請求來使用API。
:::tip
- 所有 HTTP API 均為 POST，請求和回應均為 JSON 格式（drive/files/create 除外）。
- 在請求標頭中指定
Content-Type: application/json。 - 存取權杖包含在請求內文 JSON 中，參數名為
i。 - 基礎網址是
https://{伺服器網域}/api。
:::
帶有存取權杖（中介資訊）的正文範例：
{
"i": "HogEFugA1341",
"detail": false
}
有關 API 的更多資訊，請參閱 API 參考。
:::warning Misskey 不使用 REST。 :::
此外，Misskey 不僅提供 HTTP API，還提供資料流 API。有關資料流 API 的詳細資訊，請參閱此文件。