跳转至

使用 Admin API 检索用户

getUser 和 getUsers 查询是一组 Admin API 查询，用于使用特定属性作为搜索条件，实时获取单个或多个用户的详细信息。

这组查询按支持作为搜索键的属性类型有所不同，具体查询如下：

  • getUsersByStandardAttribute(attributeName: String!, attributeValue: String!)
  • getUserByLoginID(loginIDKey: String!, loginIDValue: String!)
  • getUserByOAuth(oauthProviderAlias: String!, oauthProviderUserID: String!)

users 查询与 getUser/getUsers 查询的区别

users 查询是另一种用于检索用户的查询类型。接下来，我们将讨论 getUser/getUsers 查询与 users 查询之间的区别。

  • 即时一致： getUser 和 getUsers 查询会直接在数据库中搜索用户，而 users 查询依赖搜索索引。因此，users 查询可能无法返回最近编辑过的用户的详细信息，而 getUser 和 getUsers 查询则具有即时一致性。
  • 精确匹配：getUser 和 getUsers 查询只返回完全匹配的结果，而调用 users 查询时，只要用户的邮箱、电话号码或姓名部分匹配即可能返回结果。
  • 特定属性：使用 getUser 和 getUsers 查询时，您需要指定按邮箱、用户名或电话号码检索用户；而 users 查询则只使用一个 searchKeyword 字段。

说明

使用 users 查询可以在搜索词不完全匹配的情况下查找用户。例如，使用「John」搜索全名为「John Doe」的用户。

使用 getUser 和 getUsers 查询可以在最近发生写入操作后获取用户数据。请注意，getUser 和 getUsers 查询都不能用于按用户姓名或本页未提及的其他属性搜索用户。

以下部分包含 getUser 和 getUsers 查询中每个查询的详细说明和示例：

1. getUsersByStandardAttribute

getUsersByStandardAttribute 查询提供了一种使用预定义标准属性作为搜索键来检索用户的方式。以下是您可以使用的标准属性（attributeName）：

  • email
  • preferred_username
  • phone_number

您可以使用 getUsersByStandardAttribute 查询，获取通过 loginID 或 OAuth 连接注册的用户的详细信息。例如，您可以使用标准属性中的 email 字段作为搜索键，查找通过 OAuth 连接关联了邮箱地址，或使用邮箱和密码登录方式注册的用户。

Schema：

getUsersByStandardAttribute(
attributeName: String!
attributeValue: String!
): [User!]!

输入参数：

  • attributeName：用作搜索键的标准属性名称，取值只能是 email、preferred_username 或 phone_number。
  • attributeValue：您用作搜索键的用户标准属性（attributeName）对应的实际值。例如，如果将 attributeName 设为 email，则该值应为用户的完整邮箱地址。

示例：

query {
  getUsersByStandardAttribute(attributeName: "email", attributeValue: "user@example.com") {
    id,
    standardAttributes
  }
}

{
  "data": {
    "getUsersByStandardAttribute": [
      {
        "id": "VXNlciklODRkMzdjZi1hZDQ5LTRiZDItOTMzZJ2tOGY1YThlYjc34RE",
        "standardAttributes": {
          "email": "user@example.com",
          "email_verified": true,
          "family_name": "Aboyi",
          "given_name": "John",
          "name": "John Doe",
          "nickname": "Pius",
          "picture": "https://platform-lookaside.fbsbx.com/.../",
          "updated_at": 1724858514
        }
      }
    ]
  }
}

2. getUserByLoginID

使用 getUserByLoginID 查询，可以通过用户的 loginID 作为搜索键来检索用户详细信息。支持以下几种 loginID 类型：

  • email
  • username
  • phone

注意：仅通过社交/企业登录（OAuth）提供方关联到用户账号的邮箱地址，不能作为 getUserByLoginID 查询的搜索键。如需搜索仅通过 OAuth 提供方关联的邮箱地址，请改用 getUsersByStandardAttribute。

Schema：

getUserByLoginID(
  loginIDValue: String!
  loginIDKey: String!
): User

输入参数：

  • loginIDKey：该字段的值应为与用户账号关联的 loginID 类型（email、phone 或 username）。
  • loginIDValue：输入与用户账号关联的身份的确切值。例如，如果身份类型是 email，则填写用户的完整邮箱地址；如果是 phone，请使用包含「+」号和国家代码的完整电话号码，例如 +441234567890。

示例：

以下示例展示了 getUserByLoginID 查询及找到用户时返回的响应。

query {
  getUserByLoginID(loginIDKey: "email", loginIDValue: "user@example.com") {
    id,
    standardAttributes
  }
}

{
  "data": {
    "getUserByLoginID": {
      "id": "VXNlciklODRkMzdjZi1hZDQ5LTRiZDItOTMzZJ2tOGY1YThlYjc34RE",
      "standardAttributes": {
        "email": "user@example.com",
        "email_verified": true,
        "family_name": "Doe",
        "given_name": "John",
        "updated_at": 1724854753
      }
    }
  }
}

3. getUserByOAuth

getUserByOAuth 查询允许您检索通过社交/企业提供方关联了身份的用户的详细信息。例如，您可以使用 getUserByOAuth 查询，以 Facebook OAuth 提供方签发的用户 ID（sub）作为搜索键，查找将账号关联到 Facebook 的用户。

Schema：

getUserByOAuth(
  oauthProviderAlias: String!
  oauthProviderUserID: String!
): User

输入参数：

  • oauthProviderAlias：这是每个 OAuth 提供方的标识符，可以在 Authany 管理台的 身份验证 > 社交 / 企业登录 中设置。各社交登录提供方对应的默认值分别为 google、facebook、github、apple。
  • oauthProviderUserID：该字段的值应为 OAuth 提供方返回的 sub（用户 ID）。您可以在用户的 oauthConnections.claims 下的 id 字段中查看其 oauthProviderUserID 的值。要了解各 OAuth 提供方 sub 的更多信息，请参阅其官方文档。此页面 展示了一个来自 Facebook 的 sub 示例。

示例

query {
  getUserByOAuth(oauthProviderAlias: "facebook", oauthProviderUserID: "1234567812730389") {
    id,
    oauthConnections {
      claims
    }
  }
}

{
  "data": {
    "getUserByOAuth": {
      "id": "VXNlciklODRkMzdjZi1hZDQ5LTRiZDItOTMzZJ2tOGY1YThlYjc34RE",
      "oauthConnections": [
        {
          "claims": {
            "email": "user@example.com",
            "family_name": "Doe",
            "given_name": "John",
            "https://authgear.com/claims/oauth/profile": {
              "email": "user@example.com",
              "first_name": "John",
              "id": "1234567812730389",
              "last_name": "Doe",
              "name": "John Doe",
              "name_format": "{first} {last}",
              "picture": {
                "data": {
                  "height": 50,
                  "is_silhouette": false,
                  "url": "https://platform-lookaside.fbsbx.com/..../",
                  "width": 50
                }
              },
              "short_name": "John"
            },
            "https://authgear.com/claims/oauth/provider_alias": "facebook",
            "https://authgear.com/claims/oauth/provider_type": "facebook",
            "https://authgear.com/claims/oauth/subject_id": "1234567812730389",
            "name": "John Doe",
            "nickname": "John",
            "picture": "https://platform-lookaside.fbsbx.com/../"
          }
        }
      ]
    }
  }
}