สร้างโปรแกรมเชื่อมต่อข้อมูลประจําตัว

โดยค่าเริ่มต้น Google Cloud Search จะจดจำเฉพาะข้อมูลประจำตัวของ Google ที่จัดเก็บไว้ในไดเรกทอรี Google Cloud (ผู้ใช้และกลุ่ม) เท่านั้น เครื่องมือเชื่อมต่อข้อมูลประจำตัวจะใช้ในการซิงค์ข้อมูลประจำตัวขององค์กรกับข้อมูลประจำตัวของ Google ที่ Google Cloud Search ใช้

Google มีตัวเลือกต่อไปนี้ในการพัฒนาเครื่องมือเชื่อมต่อข้อมูลประจำตัว

  • Identity Connector SDK ตัวเลือกนี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่กำลังเขียนโปรแกรมในภาษาโปรแกรม Java Identity Connector SDK คือ Wrapper ของ REST API ซึ่งช่วยให้คุณสร้างเครื่องมือเชื่อมต่อได้อย่างรวดเร็ว หากต้องการสร้างเครื่องมือเชื่อมต่อข้อมูลประจำตัวโดยใช้ SDK โปรดดูหัวข้อสร้างเครื่องมือเชื่อมต่อข้อมูลประจำตัวโดยใช้ SDK เครื่องมือเชื่อมต่อข้อมูลประจำตัว

  • ไลบรารี REST API และ API ระดับต่ำ ตัวเลือกเหล่านี้มีไว้สำหรับนักพัฒนาซอฟต์แวร์ที่อาจไม่ได้เขียนโปรแกรมใน Java หรือที่มีฐานของโค้ดซึ่งรองรับ API ของ REST หรือไลบรารีมากกว่า หากต้องการสร้างเครื่องมือเชื่อมต่อข้อมูลประจำตัวโดยใช้ REST API โปรดดู Directory API: บัญชีผู้ใช้ เพื่อดูข้อมูลเกี่ยวกับการแมปผู้ใช้ และ เอกสารประกอบของ Cloud Identity เพื่อดูข้อมูลเกี่ยวกับกลุ่มการแมป

สร้างเครื่องมือเชื่อมต่อข้อมูลประจำตัวโดยใช้ Identity Connector SDK

เครื่องมือเชื่อมต่อข้อมูลประจำตัวทั่วไปจะทำงานต่อไปนี้

  1. กำหนดค่าเครื่องมือเชื่อมต่อ
  2. เรียกข้อมูลผู้ใช้ทั้งหมดจากระบบข้อมูลประจำตัวขององค์กรและส่งไปยัง Google เพื่อซิงค์กับข้อมูลประจำตัวของ Google
  3. เรียกดูกลุ่มทั้งหมดจากระบบข้อมูลประจำตัวขององค์กรและส่งไปยัง Google เพื่อซิงค์กับข้อมูลประจำตัวของ Google

ตั้งค่าทรัพยากร Dependency

คุณต้องรวมทรัพยากร Dependency บางอย่างในไฟล์บิลด์เพื่อใช้ SDK คลิกแท็บด้านล่างเพื่อดูทรัพยากร Dependency สำหรับสภาพแวดล้อมของบิลด์

Maven

<dependency>
<groupId>com.google.enterprise.cloudsearch</groupId>
<artifactId>google-cloudsearch-identity-connector-sdk</artifactId>
<version>v1-0.0.3</version>
</dependency>

Gradle

 compile group: 'com.google.enterprise.cloudsearch',
         name: 'google-cloudsearch-identity-connector-sdk',
         version: 'v1-0.0.3'

สร้างการกำหนดค่าเครื่องมือเชื่อมต่อ

เครื่องมือเชื่อมต่อทุกรายการจะมีไฟล์การกำหนดค่าที่มีพารามิเตอร์ที่เครื่องมือเชื่อมต่อใช้ เช่น รหัสสำหรับที่เก็บ พารามิเตอร์จะได้รับการกำหนดเป็นคู่คีย์-ค่า เช่น api.sourceId=1234567890abcdef

Google Cloud Search SDK มีพารามิเตอร์การกำหนดค่าที่ Google จัดหาให้หลายรายการที่เครื่องมือเชื่อมต่อทั้งหมดใช้ คุณต้องประกาศพารามิเตอร์ต่อไปนี้ที่ Google มีให้ในไฟล์การกำหนดค่า

  • สำหรับเครื่องมือเชื่อมต่อเนื้อหา คุณต้องประกาศ api.sourceId และ api.serviceAccountPrivateKeyFile เนื่องจากพารามิเตอร์เหล่านี้จะระบุตำแหน่งของที่เก็บและคีย์ส่วนตัวที่จำเป็นในการเข้าถึงที่เก็บ
  • สำหรับเครื่องมือเชื่อมต่อข้อมูลประจำตัว คุณต้องประกาศ api.identitySourceId เนื่องจากพารามิเตอร์นี้ระบุตำแหน่งของแหล่งที่มาของข้อมูลประจำตัวภายนอก หากซิงค์ผู้ใช้ คุณต้องประกาศ api.customerId เป็นรหัสที่ไม่ซ้ำกันสำหรับบัญชี Google Workspace ขององค์กรด้วย

คุณไม่จำเป็นต้องประกาศค่าเริ่มต้นในไฟล์การกำหนดค่า เว้นแต่ว่าคุณต้องการลบล้างค่าเริ่มต้นสำหรับพารามิเตอร์อื่นๆ ที่ Google มีให้ ดูข้อมูลเพิ่มเติมเกี่ยวกับพารามิเตอร์การกำหนดค่าที่ Google มีให้ เช่น วิธีสร้างรหัสและคีย์บางรายการได้ที่พารามิเตอร์การกำหนดค่าที่ Google จัดหาให้

คุณยังสามารถกำหนดพารามิเตอร์เฉพาะสำหรับที่เก็บของคุณเองเพื่อใช้ในไฟล์การกำหนดค่าได้อีกด้วย

ส่งไฟล์การกำหนดค่าไปยังเครื่องมือเชื่อมต่อ

ตั้งค่าพร็อพเพอร์ตี้ของระบบ config เพื่อส่งไฟล์การกำหนดค่าไปยังเครื่องมือเชื่อมต่อ คุณสามารถตั้งค่าพร็อพเพอร์ตี้โดยใช้อาร์กิวเมนต์ -D เมื่อเริ่มเครื่องมือเชื่อมต่อ ตัวอย่างเช่น คำสั่งต่อไปนี้จะเริ่มต้นเครื่องมือเชื่อมต่อด้วยไฟล์การกำหนดค่า MyConfig.properties

java -classpath myconnector.jar;... -Dconfig=MyConfig.properties MyConnector

ถ้าไม่มีอาร์กิวเมนต์นี้ SDK จะพยายามเข้าถึงไฟล์การกำหนดค่าเริ่มต้นชื่อ connector-config.properties

สร้างเครื่องมือเชื่อมต่อข้อมูลประจำตัวการซิงค์แบบเต็มโดยใช้คลาสเทมเพลต

Identity Connector SDK มีคลาสเทมเพลต FullSyncIdentityConnector ที่ใช้ซิงค์ผู้ใช้และกลุ่มทั้งหมดจากที่เก็บข้อมูลประจำตัวกับข้อมูลประจำตัวของ Google ได้ ส่วนนี้จะอธิบายวิธีใช้เทมเพลต FullSyncIdentityConnector เพื่อซิงค์ผู้ใช้และกลุ่มจากที่เก็บข้อมูลประจำตัวที่ไม่ใช่ของ Google อย่างเต็มรูปแบบ

ส่วนนี้ของเอกสารหมายถึงข้อมูลโค้ดจากตัวอย่าง IdentityConnecorSample.java ตัวอย่างนี้อ่านข้อมูลประจำตัวของผู้ใช้และกลุ่มจากไฟล์ CSV 2 ไฟล์และซิงค์เข้ากับข้อมูลประจำตัวของ Google

ใช้งานจุดแรกเข้าของเครื่องมือเชื่อมต่อ

จุดแรกเข้าของเครื่องมือเชื่อมต่อคือเมธอด main() งานหลักของเมธอดนี้คือการสร้างอินสแตนซ์ของคลาส Application และเรียกใช้เมธอด start() เพื่อเรียกใช้เครื่องมือเชื่อมต่อ

ก่อนเรียกใช้ application.start() ให้ใช้คลาส IdentityApplication.Builder เพื่อสร้างอินสแตนซ์FullSyncIdentityConnector FullSyncIdentityConnector ยอมรับออบเจ็กต์ Repository ซึ่งจะมีเมธอดที่คุณจะใช้ ข้อมูลโค้ดต่อไปนี้จะแสดงวิธีใช้เมธอด main()

IdentityConnectorSample.java
/**
 * This sample connector uses the Cloud Search SDK template class for a full
 * sync connector. In the full sync case, the repository is responsible
 * for providing a snapshot of the complete identity mappings and
 * group rosters. This is then reconciled against the current set
 * of mappings and groups in Cloud Directory.
 *
 * @param args program command line arguments
 * @throws InterruptedException thrown if an abort is issued during initialization
 */
public static void main(String[] args) throws InterruptedException {
  Repository repository = new CsvRepository();
  IdentityConnector connector = new FullSyncIdentityConnector(repository);
  IdentityApplication application = new IdentityApplication.Builder(connector, args).build();
  application.start();
}

SDK จะเรียกใช้เมธอด initConfig() ในเบื้องหลังหลังจากเรียกเมธอด main() ของเครื่องมือเชื่อมต่อ Application.build เมธอด initConfig() จะทำงานต่อไปนี้

  1. เรียกใช้เมธอด Configuation.isInitialized() เพื่อตรวจสอบว่าไม่มีการกำหนดค่าเริ่มต้น Configuration
  2. เริ่มต้นออบเจ็กต์ Configuration ด้วยคู่คีย์-ค่าที่ Google จัดหา คู่คีย์-ค่าแต่ละคู่จะจัดเก็บอยู่ในออบเจ็กต์ ConfigValue ภายในออบเจ็กต์ Configuration

ใช้อินเทอร์เฟซ Repository

วัตถุประสงค์เพียงอย่างเดียวของออบเจ็กต์ Repository คือการซิงค์ข้อมูลประจำตัวของที่เก็บกับข้อมูลประจำตัวของ Google เมื่อใช้เทมเพลต คุณจะต้องลบล้างบางเมธอดภายในอินเทอร์เฟซ Repository เท่านั้นเพื่อสร้างเครื่องมือเชื่อมต่อข้อมูลประจำตัว สำหรับ FullTraversalConnector คุณอาจลบล้างวิธีการต่อไปนี้

  • เมธอด init() หากต้องการตั้งค่าและเริ่มต้นที่เก็บข้อมูลประจำตัว ให้ลบล้างเมธอด `init()

  • เมธอด listUsers() หากต้องการซิงค์ผู้ใช้ทั้งหมดในที่เก็บข้อมูลประจำตัวกับผู้ใช้ Google ให้ลบล้างเมธอด listUsers()

  • เมธอด listGroups() หากต้องการซิงค์กลุ่มทั้งหมดในที่เก็บข้อมูลประจำตัวกับ Google Groups ให้ลบล้างเมธอด listGroups()

  • (ไม่บังคับ) เมธอด close() หากต้องการล้างที่เก็บ ให้ลบล้างเมธอด close() เมธอดนี้จะมีการเรียกเพียงครั้งเดียวระหว่างการปิดโปรแกรมเชื่อมต่อ

รับพารามิเตอร์การกำหนดค่าที่กำหนดเอง

ในการจัดการการกำหนดค่าเครื่องมือเชื่อมต่อ คุณจะต้องรับพารามิเตอร์ที่กำหนดเองจากออบเจ็กต์ Configuration งานนี้มักจะดำเนินการในเมธอด init() ของ Repository ชั้นเรียน

คลาส Configuration มีหลายวิธีในการรับข้อมูลประเภทต่างๆ จากการกำหนดค่า แต่ละเมธอดจะแสดงผลออบเจ็กต์ ConfigValue จากนั้นจะใช้เมธอด get() ของออบเจ็กต์ ConfigValue เพื่อดึงค่าจริง ข้อมูลโค้ดต่อไปนี้แสดงวิธีดึงค่า userMappingCsvPath และ groupMappingCsvPath จากออบเจ็กต์ Configuration

IdentityConnectorSample.java
/**
 * Initializes the repository once the SDK is initialized.
 *
 * @param context Injected context, contains convenienve methods
 *                for building users & groups
 * @throws IOException if unable to initialize.
 */
@Override
public void init(RepositoryContext context) throws IOException {
  log.info("Initializing repository");
  this.context = context;
  userMappingCsvPath = Configuration.getString(
      "sample.usersFile", "users.csv").get().trim();
  groupMappingCsvPath = Configuration.getString(
      "sample.groupsFile", "groups.csv").get().trim();
}

หากต้องการรับและแยกวิเคราะห์พารามิเตอร์ที่มีค่าหลายค่า ให้ใช้โปรแกรมแยกวิเคราะห์ประเภทConfigurationตัวใดตัวหนึ่งของคลาสเพื่อแยกวิเคราะห์ข้อมูลออกเป็นส่วนๆ แยกกัน ข้อมูลโค้ดต่อไปนี้จากเครื่องมือเชื่อมต่อบทแนะนำจะใช้เมธอด getMultiValue เพื่อรับรายการชื่อที่เก็บ GitHub

GithubRepository.java
ConfigValue<List<String>> repos = Configuration.getMultiValue(
    "github.repos",
    Collections.emptyList(),
    Configuration.STRING_PARSER);

รับการแมปสำหรับผู้ใช้ทั้งหมด

ลบล้าง listUsers() เพื่อเรียกข้อมูลการแมปสำหรับผู้ใช้ทั้งหมดจากที่เก็บข้อมูลประจำตัวของคุณ เมธอด listUsers() จะยอมรับจุดตรวจที่แสดงข้อมูลประจำตัวล่าสุดที่จะซิงค์ คุณสามารถใช้จุดตรวจเพื่อทำให้การซิงค์กลับมาทำงานอีกครั้งได้หากกระบวนการหยุดชะงัก สำหรับผู้ใช้แต่ละรายในที่เก็บ คุณจะต้องทำตามขั้นตอนเหล่านี้ในเมธอด listUsers()

  1. รับการแมปที่ประกอบด้วยข้อมูลประจำตัวของ Google และข้อมูลข้อมูลประจำตัวภายนอกที่เชื่อมโยง
  2. ทำแพ็กเกจทั้งคู่ลงในตัววนซ้ำซึ่งแสดงผลโดยเมธอด listUsers()

รับการแมปผู้ใช้

ข้อมูลโค้ดต่อไปนี้แสดงวิธีเรียกการจับคู่ข้อมูลประจำตัวที่จัดเก็บไว้ในไฟล์ CSV

IdentityConnectorSample.java
/**
 * Retrieves all user identity mappings for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the mappings. This is reconciled against the current mappings
 * in Cloud Directory. All identity mappings returned here are
 * set in Cloud Directory. Any previously mapped users that are omitted
 * are unmapped.
 *
 * The connector does not create new users. All users are assumed to
 * exist in Cloud Directory.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of user identity mappings
 * @throws IOException if unable to read user identity mappings
 */
@Override
public CheckpointCloseableIterable<IdentityUser> listUsers(byte[] checkpoint)
    throws IOException {
  List<IdentityUser> users = new ArrayList<>();
  try (Reader in = new FileReader(userMappingCsvPath)) {
    // Read user mappings from CSV file
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "primary_email", "external_id"
      String primaryEmailAddress = record.get(0);
      String externalId = record.get(1);
      if (primaryEmailAddress.isEmpty() || externalId.isEmpty()) {
        // Skip any malformed mappings
        continue;
      }
      log.info(() -> String.format("Adding user %s/%s",
          primaryEmailAddress, externalId));

      // Add the identity mapping
      IdentityUser user = context.buildIdentityUser(
          primaryEmailAddress, externalId);
      users.add(user);
    }
  }
  // ...
}

รวมการแมปผู้ใช้ไว้ในตัววนซ้ำ

เมธอด listUsers() จะแสดงผลค่า Iterator โดยเฉพาะออบเจ็กต์ CheckpointCloseableIterable ของ IdentityUser คุณใช้คลาส CheckpointClosableIterableImpl.Builder เพื่อสร้างและแสดงผลตัววนซ้ำได้ ข้อมูลโค้ดต่อไปนี้แสดงวิธีจัดแพ็กเกจการแมปแต่ละรายการเป็นรายการ ๆ แล้วสร้างอิเทอเรเตอร์จากลิสต์นั้น

IdentityConnectorSample.java
CheckpointCloseableIterable<IdentityUser> iterator =
  new CheckpointCloseableIterableImpl.Builder<IdentityUser>(users)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

รับกลุ่ม

ลบล้าง listGroups() เพื่อเรียกข้อมูลกลุ่มและสมาชิกทั้งหมดจากที่เก็บข้อมูลประจำตัว เมธอด listGroups() จะยอมรับจุดตรวจสอบที่แสดงข้อมูลประจำตัวล่าสุดที่จะซิงค์ จุดตรวจสอบนี้สามารถใช้เพื่อดำเนินการซิงค์ต่อได้หากกระบวนการหยุดชะงัก สำหรับผู้ใช้แต่ละรายในที่เก็บ คุณจะต้องทำตามขั้นตอนเหล่านี้ในเมธอด listGroups()

  1. เรียกกลุ่มและสมาชิก
  2. จัดแพ็กเกจแต่ละกลุ่มและสมาชิกลงในตัววนซ้ำ ซึ่งแสดงผลโดยเมธอด listGroups()

สร้างข้อมูลประจำตัวของกลุ่ม

ข้อมูลโค้ดต่อไปนี้แสดงวิธีเรียกข้อมูลกลุ่มและสมาชิกที่จัดเก็บไว้ในไฟล์ CSV

IdentityConnectorSample.java
/**
 * Retrieves all group rosters for the identity source. For the
 * full sync connector, the repository must provide a complete snapshot
 * of the rosters. This is reconciled against the current rosters
 * in Cloud Directory. All groups and members  returned here are
 * set in Cloud Directory. Any previously created groups or members
 * that are omitted are removed.
 *
 * @param checkpoint Saved state if paging over large result sets. Not used
 *                   for this sample.
 * @return Iterator of group rosters
 * @throws IOException if unable to read groups
 */    @Override
public CheckpointCloseableIterable<IdentityGroup> listGroups(byte[] checkpoint)
    throws IOException {
  List<IdentityGroup> groups = new ArrayList<>();
  try (Reader in = new FileReader(groupMappingCsvPath)) {
    // Read group rosters from CSV
    CSVParser parser = CSVFormat.RFC4180
        .withIgnoreSurroundingSpaces()
        .withIgnoreEmptyLines()
        .withCommentMarker('#')
        .parse(in);
    for (CSVRecord record : parser.getRecords()) {
      // Each record is in form: "group_id", "member"[, ..., "memberN"]
      String groupName = record.get(0);
      log.info(() -> String.format("Adding group %s", groupName));
      // Parse the remaining columns as group memberships
      Supplier<Set<Membership>> members = new MembershipsSupplier(record);
      IdentityGroup group = context.buildIdentityGroup(groupName, members);
      groups.add(group);
    }
  }
  // ...

}

รวมกลุ่มและสมาชิกไว้ในตัววนซ้ำ

เมธอด listGroups() จะแสดงผลค่า Iterator โดยเฉพาะออบเจ็กต์ CheckpointCloseableIterable ของ IdentityGroup คุณใช้คลาส CheckpointClosableIterableImpl.Builder เพื่อสร้างและแสดงผลตัววนซ้ำได้ ข้อมูลโค้ดต่อไปนี้จะแสดงวิธีการรวมกลุ่มและสมาชิกแต่ละกลุ่มลงในรายการ และสร้างตัววนซ้ำจากรายการนั้น

IdentityConnectorSample.java
CheckpointCloseableIterable<IdentityGroup> iterator =
   new CheckpointCloseableIterableImpl.Builder<IdentityGroup>(groups)
      .setHasMore(false)
      .setCheckpoint((byte[])null)
      .build();

ขั้นตอนถัดไป

ขั้นตอนถัดไป 2-3 อย่างที่คุณอาจดำเนินการมีดังนี้