使用用户导出 API 导出用户¶

用户导出 API 提供了一种方法，可以将您 Authany 项目中的用户数据（如用户 ID、邮箱、手机号等）导出为 CSV 或 ndjson 文件。

本指南将介绍如何使用用户导出 API。

用户导出 API¶

用户导出 API 允许开发者将用户批量导出到文件中。

导出过程是异步的，也就是说该过程在后台运行。因此，您需要先调用一个端点发起导出任务，然后再调用另一个端点查询该导出任务的状态。

要向用户导出 API 的端点发送 HTTP(S) 请求，您的应用必须在 Bearer Authorization 请求头中使用 Admin API JWT 令牌进行身份验证。如果使用了无效的 JWT，API 将返回 “403 Forbidden” 错误。

用户导出 API 有以下两个端点：

发起导出任务¶

POST /_api/admin/users/export

使用此端点创建新的用户导出任务。

请求头

名称	值
Content-Type	`application/json`
Authorization	`Bearer <Admin API JWT Token>`
Host	`<Your Authgear Project domain>`

请求体

发起导出端点通过 HTTP(S) 请求体接收 JSON 格式的输入。以下是输入示例：

{
  "format": "csv",
  "csv": {
    "fields": [
      {
        "pointer": "/sub",
        "field_name": "user_id"
      },
      {
        "pointer": "/email"
      }
    ]
  }
}

format 字段用于指定导出文件的格式，取值可以是 csv 或 ndjson。
csv：当 format 设为 csv 时使用此字段，取值是一个包含 fields 属性的对象。
csv.fields：您可以使用此字段列出要作为 CSV 文件字段包含的所有用户属性。取值应为一个数组，数组中的每一项都是一个对象，用 pointer 属性和可选的 field_name 属性描述一个用户属性。

查询状态¶

GET /_api/admin/users/export/{Task ID}

使用此端点查询现有导出任务的状态。将 {Task ID} 替换为发起导出端点响应体中返回的任务 id。

请求头

名称	值
Authorization	`Bearer <Admin API JWT Token>`
Host	`<Your Authgear Project domain>`

说明

如需了解端点、输入参数和 pointer 字段的更多详情，请参阅用户导出 API 参考。

示例：使用用户导出 API¶

以下示例演示如何在 Node.js 应用中使用用户导出 API。

步骤 1：获取 Admin API JWT¶

首先，您需要获取用于对端点请求进行身份验证的 Admin API JWT。

为此，请运行以下命令安装 JsonWebToken（一个用于生成 JWT 的 Node 包）：

npm install jsonwebtoken

现在，在您的 Express 应用中创建一个 generateJWT() 函数来生成 JWT：

const node_jwt = require('jsonwebtoken');
const fs = require("fs");

function generateJWT() {
    const project_id = ""; //Your authgear app id
    const key_id = ""; //you authgear key ID
    const expiresAt = Math.floor(Date.now() / 1000) + (60 * 60); //the current value means token will expire in 1 hour.

    //Payload to include in JWT
    const claims = {
        aud: project_id,
        iat: Math.floor(Date.now() / 1000) - 30,
        exp: expiresAt
    }
    const privateKey = fs.readFileSync("key.pem"); //Read value from the downloaded key file
    const header = { "typ": "JWT", "kid": key_id, "alg": "RS256" }
    const jwt = node_jwt.sign(claims, privateKey, { header: header });

    return jwt;
}

有关如何获取密钥 ID 和私钥，以及如何使用不同编程语言生成 Admin API JWT 的详细指南，请参阅 Admin API 身份验证。

步骤 2：发起用户导出任务¶

向发起导出端点发送 HTTP(S) POST 请求，以发起新的用户导出任务。

为此，请先使用以下命令在您的应用中安装 node-fetch 包：

npm install node-fetch

然后将以下代码添加到您的应用中：

const express = require("express");
const node_jwt = require("jsonwebtoken");
const fs = require("fs");
const fetch = require("node-fetch");
const app = express();
const port = 3002;

app.get("/export", (request, response) => {
  const jwt = generateJWT();
  const input = {
    format: "csv",
    csv: {
      fields: [
        {
          pointer: "/sub",
          field_name: "user_id",
        },
        {
          pointer: "/email",
        },
      ],
    },
  };

  const options = {
    method: "POST",
    headers: {
      "Content-type": "application/json",
      Authorization: "Bearer " + jwt,
    },
    body: JSON.stringify(input),
  };

  const appUrl = "https://your-project.authanyid.com";

  fetch(`${appUrl}/_api/admin/users/export`, options)
    .then((result) => result.json())
    .then((result) => response.send(result))
    .catch((error) => response.send(error));
});

app.listen(port, () => {
  console.log("server started! PORT: " + port);
});

此步骤中 HTTP(S) 请求的响应应如下所示：

响应

{
    "result": {
        "id": "userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ",
        "created_at": "2024-10-07T21:06:24.361634372Z",
        "status": "pending",
        "request": {
            "format": "csv",
            "csv": {
                "fields": [
                    {
                        "pointer": "/sub",
                        "field_name": "user_id"
                    },
                    {
                        "pointer": "/email"
                    },
                    {
                        "pointer": "/mfa/emails"
                    }
                ]
            }
        }
    }
}

id：id 的值就是任务 ID，可用于在查询状态端点中查询任务并获取导出文件的下载链接。

步骤 3：查询用户导出任务的状态¶

在此步骤中，我们将通过向查询状态端点（/_api/admin/users/export/{Task ID}）发送 HTTP(S) 请求，来检查上一步发起的导出任务的状态。将 URL 中的 {Task ID} 替换为上一步导出任务的任务 ID。

在您的应用中添加以下路由，通过任务 ID 查询导出任务的状态：

app.get("/status/:id", (request, response) => {
  const jwt = generateJWT();

  const options = {
    method: "GET",
    headers: {
      "Content-type": "application/json",
      Authorization: "Bearer " + jwt,
    },
  };

  const appUrl = "https://your-project.authanyid.com";

  fetch(`${appUrl}/_api/admin/users/export/${request.params.id}`, options)
    .then((result) => result.json())
    .then((result) => response.send(result))
    .catch((error) => response.send(error));

});

当任务状态为已完成时，HTTP(S) 响应体将如下所示：

响应

{
    "result": {
        "id": "userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ",
        "created_at": "2024-10-07T21:06:24.361634372Z",
        "completed_at": "2024-10-07T21:06:24.551711713Z",
        "status": "completed",
        "request": {
            "format": "csv",
            "csv": {
                "fields": [
                    {
                        "pointer": "/sub",
                        "field_name": "user_id"
                    },
                    {
                        "pointer": "/email"
                    },
                    {
                        "pointer": "/mfa/emails"
                    }
                ]
            }
        },
        "download_url": "https://storage.googleapis.com/authgear-userexport-staging/example-userexport_userexport_VWFAACAMB5V0BY1J7KK5NS3GV1TQAACQ-20241007210624Z.csv?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=authgear-server%40oursky-kube.iam.gserviceaccount.com%2F20241007%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20241007T210641Z&X-Goog-Expires=59&X-Goog-Signature=abcd12e45&X-Goog-SignedHeaders=host"
    }
}

download_url：打开 download_url 值中的 URL，即可下载导出的用户文件。

注意： 已完成导出任务的结果将在 24 小时后过期。因此，24 小时后，您将无法再使用该任务对应的任务 ID 生成新的下载链接。