通義靈碼 API 同步配置指南 - 用戶與組織架構(gòu)同步

9.5.6.8. API 同步

API 同步支持企業(yè)通過(guò)集成企業(yè)提供的用戶數(shù)據(jù)接口，同步企業(yè)內(nèi)的用戶和組織架構(gòu)信息。

創(chuàng)建范圍外用戶

企業(yè)管理員可以在企業(yè)管理 > 第三方集成中添加和管理 API 同步，請(qǐng)確保 API 按照此文檔中的規(guī)范提供，通義靈碼靈碼會(huì)按照配置的 URL 執(zhí)行企業(yè)組織架構(gòu)和用戶的同步，可以勾選支持內(nèi)建用戶，可以創(chuàng)建同步范圍外的用戶。

配置 API 同步

步驟一 配置數(shù)據(jù)請(qǐng)求地址

支持 http、https 接口請(qǐng)求的 URL，請(qǐng)保證 URL 的準(zhǔn)確性和接口的連通性，配置后等待接口連通性檢查通過(guò)后，單擊下一步。

說(shuō)明

1. 請(qǐng)求接口只支持 HTTP 和 HTTPS 協(xié)議的 GET 請(qǐng)求。

2. 由于此處只提供了 URL，未提供接口鑒權(quán)的額外配置方式，請(qǐng)自行在提供的URL中增加鑒權(quán)參數(shù)對(duì)接口調(diào)用鑒權(quán)。

3. 如需支持分頁(yè)，請(qǐng)?jiān)?URL 中增加第一頁(yè)的分頁(yè)參數(shù)，保證數(shù)據(jù)的完整性，如：https://xxxxxx?page_number=0&page_size=10，其中page_number為頁(yè)碼，page_size為每頁(yè)用戶條數(shù)。

企業(yè)接口返回?cái)?shù)據(jù)說(shuō)明

需要按照以下內(nèi)容定義接口返回?cái)?shù)據(jù)：

其中departments為users用戶列表中包含的所有部門的信息，返回結(jié)果如需分頁(yè)，按照用戶數(shù)量進(jìn)行分頁(yè)，且必須保證父部門提前返回。

示例響應(yīng)結(jié)果：

{
  "users": [
    {
      "user_id": "yx12346xxx",
      "name": "周x",
      "user_name": "zhouxxx",
      "nick_name": "x外",
      "staff_id": "004xx5",
      "email": "zhouxxx@alibaba-inc.com",
      "department_ids": [
        "16xxx2"
      ]
    }
  ],
  "departments": [
    {
      "department_id": "009xxx",
      "name": "阿xxx-阿xxx群-阿xxx部",
      "parent_id": "19xxx5"
    }
  ],
  "next_page_number": 1
}

步驟二 配置賬號(hào)綁定與屬性映射

目前提供 4 種賬號(hào)識(shí)別和綁定方式：

• 自動(dòng)綁定郵箱相同的賬號(hào)：按照同步策略，自動(dòng)將通義靈碼靈碼、企業(yè)用戶數(shù)據(jù)接口中郵箱賬號(hào)相同的用戶綁定在一起。

• 自動(dòng)綁定登錄賬號(hào)相同的賬號(hào)：按照同步策略，自動(dòng)將通義靈碼靈碼、企業(yè)用戶數(shù)據(jù)接口中登錄賬號(hào)相同的用戶綁定在一起。

• 自動(dòng)綁定手機(jī)號(hào)相同的賬號(hào)：按照同步策略，自動(dòng)將通義靈碼靈碼、企業(yè)用戶數(shù)據(jù)接口中手機(jī)號(hào)相同的用戶綁定在一起。

• 自動(dòng)綁定工號(hào)相同的賬號(hào)：按照同步策略，自動(dòng)將通義靈碼靈碼、企業(yè)用戶數(shù)據(jù)接口中工號(hào)相同的用戶綁定在一起。

無(wú)論選擇哪一種賬號(hào)識(shí)別和綁定方式，均需要保證其對(duì)應(yīng)的屬性字段的唯一性和存在性，因?yàn)橥x靈碼靈碼將按照選擇的方式進(jìn)行賬號(hào)的一一匹配，選擇自動(dòng)綁定登錄賬號(hào)相同的賬號(hào)的綁定過(guò)程：

靈碼通義靈碼將按照下圖中字段映射關(guān)系，自動(dòng)將企業(yè)內(nèi)用戶信息與通義靈碼靈碼中的用戶信息，按照同步策略進(jìn)行映射同步，目前暫不支持修改字段映射關(guān)系，確認(rèn)后單擊下一步。

配置和確認(rèn)完成后，單擊下一步。

步驟三 開(kāi)啟用戶和組織同步

當(dāng)靈碼通義靈碼上未開(kāi)啟其他第三方的用戶和組織同步功能時(shí)，可以開(kāi)啟用戶和組織同步功能，支持配置同步時(shí)機(jī)、用戶差異處理、組織差異處理的規(guī)則。

• 數(shù)據(jù)同步時(shí)機(jī)：默認(rèn)為手動(dòng)同步，并支持手動(dòng)同步、定時(shí)同步的切換：

  • 手動(dòng)同步：需要企業(yè)管理員在有數(shù)據(jù)變更后，手動(dòng)在 API 同步集成詳情頁(yè)面單擊執(zhí)行手動(dòng)同步按鈕完成用戶和組織同步。

說(shuō)明

提示：每次手動(dòng)同步操作盡量間隔 1 個(gè)小時(shí)。

• 定時(shí)同步：配置同步的時(shí)機(jī)和規(guī)則按每天（某刻）、每周（某天某刻）、每月（某天某刻）、每隔一定時(shí)間進(jìn)行同步，如果設(shè)置為定時(shí)同步，建議保存配置后完成一次手動(dòng)同步，以保證數(shù)據(jù)可以及時(shí)同步至通義靈碼靈碼。

• 用戶差異處理：默認(rèn)忽略通義靈碼靈碼上多余的賬號(hào)，并為在同步范圍內(nèi)的上游賬號(hào)創(chuàng)建通義靈碼靈碼賬號(hào)并綁定，可根據(jù)訴求修改：

  • 已有通義靈碼靈碼賬號(hào)未匹配到上游賬號(hào)-忽略：當(dāng)已有通義靈碼靈碼賬號(hào)未匹配到上游賬號(hào)時(shí)，不刪除通義靈碼靈碼上的多余賬號(hào)。

  • 已有靈碼通義靈碼賬號(hào)未匹配到上游賬號(hào)-刪除通義靈碼靈碼賬號(hào)：當(dāng)已有通義靈碼靈碼賬號(hào)未匹配到上游賬號(hào)時(shí)，刪除通義靈碼靈碼上的賬號(hào)。

  • 已有上游賬號(hào)未匹配到通義靈碼靈碼賬號(hào)-忽略：當(dāng)已有上游賬號(hào)未匹配到通義靈碼靈碼賬號(hào)時(shí)，不在通義靈碼靈碼上創(chuàng)建新賬號(hào)。

  • 已有上游賬號(hào)未匹配到靈碼通義靈碼賬號(hào)-新建靈碼通義靈碼賬號(hào)并綁定：當(dāng)已有上游賬號(hào)未匹配到靈碼通義靈碼賬號(hào)時(shí)，會(huì)按照賬號(hào)綁定和屬性映射規(guī)則在靈碼通義靈碼上創(chuàng)建新賬號(hào)，并與上游賬號(hào)綁定。

• 組織差異處理：默認(rèn)忽略通義靈碼靈碼上多余的部門節(jié)點(diǎn)，并且為在同步范圍內(nèi)的上游部門節(jié)點(diǎn)創(chuàng)建通義靈碼靈碼部門并綁定，可根據(jù)訴求修改：

  • 已有通義靈碼靈碼部門未匹配到上游部門-忽略：當(dāng)已有通義靈碼靈碼部門未匹配到上游部門時(shí)，不刪除通義靈碼靈碼上的部門節(jié)點(diǎn)。

  • 已有通義靈碼靈碼部門未匹配到上游部門-刪除通義靈碼靈碼部門：當(dāng)已有通義靈碼靈碼部門未匹配到上游部門時(shí)，刪除通義靈碼靈碼上的部門節(jié)點(diǎn)。

  • 已有上游部門未匹配到靈碼通義靈碼部門-忽略：當(dāng)已有上游部門未匹配到通義靈碼靈碼通義靈碼部門時(shí)，不在通義靈碼靈碼上創(chuàng)建部門節(jié)點(diǎn)。

  • 已有上游部門未匹配到靈碼通義靈碼部門-創(chuàng)建通義靈碼靈碼部門并綁定：當(dāng)已有上游部門未匹配到通義靈碼靈碼部門時(shí)，會(huì)在靈碼通義靈碼上創(chuàng)建部門節(jié)點(diǎn)，并將兩方部門節(jié)點(diǎn)進(jìn)行綁定。

如果不開(kāi)啟用戶和組織同步的情況下保存 API 同步集成配置，后續(xù)可以在 API 同步集成詳情頁(yè)面中開(kāi)啟。

當(dāng)完成所有配置后，單擊保存配置按鈕即可完成 API 同步集成的配置。

查看用戶和組織同步結(jié)果

在開(kāi)啟用戶和組織同步的情況下，打開(kāi) API 同步集成詳情頁(yè)面，可以查看最新同步結(jié)果：未執(zhí)行同步、同步成功、同步失敗、部分同步成功。

關(guān)閉用戶和組織同步

在 API 同步集成詳情頁(yè)中，已經(jīng)開(kāi)啟用戶和組織同步的情況下，可點(diǎn)擊修改服務(wù)配置，在打開(kāi)的修改配置的抽屜中可以關(guān)閉用戶和組織同步，關(guān)閉后：

• 不解除通義靈碼靈碼賬號(hào)與上游賬號(hào)的綁定關(guān)系。

• 不再執(zhí)行上游系統(tǒng)的用戶和組織同步。

移除 API 同步集成

在 API 同步集成詳情頁(yè)中，可單擊移除集成按鈕，二次確認(rèn)后即可移除 API 同步集成，移除集成后：

• 解除通義靈碼靈碼賬號(hào)和上游賬號(hào)的綁定關(guān)系。

• 已同步的用戶和組織架構(gòu)不會(huì)受到影響。