mirror of
https://iceshrimp.dev/Crimekillz/jointrashposs.git
synced 2024-11-25 02:09:05 +01:00
126 lines
4.1 KiB
Markdown
126 lines
4.1 KiB
Markdown
# 取得存取權杖
|
||
|
||
要開始使用 API，您需要取得與將使用API的帳戶相關聯的**存取權杖**。
|
||
本文件將介紹取得存取權杖的步驟，然後說明如何使用基本 API。
|
||
|
||
基本上，API需要存取權杖進行請求。
|
||
存取權杖是與用戶關聯的身份驗證資料，用於識別使用API的用戶，同時管理每個存取權杖具有什麼樣的操作權限。
|
||
|
||
:::tip
|
||
使用者和與該使用者關聯的存取權杖之間存在一對多關係，並且可以向使用者發行多個存取權杖。
|
||
:::
|
||
|
||
你可以輕鬆地獲得自己的存取權杖，也可以獲取使用你的應用程序的不特定用戶的存取權杖。
|
||
|
||
- 如果是前者：**閱讀「手動發行您自己的存取權杖」**
|
||
- 如果是後者：閱讀「**請求應用程式使用者發行存取權杖**」
|
||
|
||
### 手動發行您自己的存取權杖
|
||
|
||
您可以在 Misskey Web 的「設定 > API」中發行自己的存取權杖。
|
||
|
||
:::danger
|
||
請不要與他人分享您的存取權杖。
|
||
:::
|
||
|
||
### 請求應用程式使用者發行存取權杖
|
||
|
||
若要為使用應用程式的使用者（以下簡稱「使用者」）取得存取權杖，請依照下列步驟請求核發。
|
||
|
||
:::tip
|
||
|
||
下面描述的方法稱為 MiAuth，它無需創建應用程式即可立即發行存取權杖。
|
||
|
||
[還有一種獲取存取權杖的方法是使用應用程式建立方法（舊方法）。](./app)
|
||
:::
|
||
|
||
#### 步驟1
|
||
|
||
產生 UUID。從現在起，這將被稱為**工作階段ID**。
|
||
|
||
:::danger
|
||
此工作階段 ID 應每次生成，不應重複使用。
|
||
:::
|
||
|
||
#### 步驟2
|
||
|
||
在使用者瀏覽器中顯示應用程式授權表單。授權表格可透過以下格式的網址開啟：
|
||
|
||
```
|
||
https://{host}/miauth/{session}
|
||
```
|
||
|
||
需要變更的部份
|
||
|
||
- 將 `{host}` 替換為使用者伺服器的主機。主機通常由使用者輸入。
|
||
- 將 `{session}` 替換為工作階段 ID。
|
||
|
||
您也可以在網址中設定多個選項作為查詢參數：
|
||
|
||
| 名稱 | 說明 |
|
||
| ------------ | ------------------------------------------------------------------- |
|
||
| `name` | 應用程式名稱。 |
|
||
| `icon` | 應用程式的圖標圖像網址。 |
|
||
| `callback` | 驗證後重導向的網址。<br>重導向時，工作階段 ID 會附加到查詢參數 `session`。 |
|
||
| `permission` | 應用程式所需的權限。<br>列舉所請求的授權，以半形逗號 `,` 分隔。可以在[此處](./permission.md)查看權限清單。 |
|
||
|
||
:::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`。
|
||
|
||
:::
|
||
|
||
帶有存取權杖（中介資訊）的正文範例：
|
||
|
||
```json
|
||
{
|
||
"i": "HogEFugA1341",
|
||
"detail": false
|
||
}
|
||
```
|
||
|
||
<!--TODO:「APIリファレンス」をリンクに差し替え-->
|
||
|
||
有關 API 的更多資訊，請參閱 API 參考。
|
||
|
||
:::warning
|
||
Misskey 不使用 REST。
|
||
:::
|
||
|
||
此外，Misskey 不僅提供 HTTP API，還提供資料流 API。有關資料流 API 的詳細資訊，請參閱[此文件](./streaming/index.md)。
|