ความช่วยเหลือของ Tableau Cloud

โดยเริ่มในเดือนมิถุนายน 2022 โดยการใช้แอปที่เชื่อมต่อของ Tableau คุณจะสามารถเรียกใช้และเข้าถึง REST API ของ Tableau โดยอัตโนมัติผ่านแอปพลิเคชันที่กำหนดเองของคุณในนามของผู้ใช้ Tableau Cloud ได้ การเข้าถึง REST API is enabled by a JSON Web Token (JWT) ที่กำหนดไว้เป็นส่วนหนึ่งของคำขอเข้าสู่ระบบเริ่มต้น JWT จะต้องมีขอบเขตที่กำหนด REST API ที่พร้อมใช้งานสำหรับแอปพลิเคชันที่กำหนดเองของคุณและผู้ใช้ผ่านแอปที่เชื่อมต่อ

อนุญาตการเข้าถึง REST API โดยใช้แอปที่เชื่อมต่อเพื่อ:

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

การดำเนินการขอบเขต

แอปที่เชื่อมต่อใช้ขอบเขตที่อนุญาตการเข้าถึงเนื้อหาหรือการดำเนินการดูแลระบบผ่านเมธอด REST API ที่รองรับการรับรองสิทธิ์ของ JWT (ด้านล่าง) ขอบเขตเป็นสตริงที่คั่นด้วยโคลอนที่เริ่มต้นด้วยเนมสเปซ tableau ตามด้วยทรัพยากร Tableau ที่ได้รับอนุญาตการเข้าถึง เช่น datasources และลงท้ายด้วยการดำเนินการที่ได้รับอนุญาตบนทรัพยากร เช่น update

การดำเนินการที่ขอบเขตสามารถทำได้มีดังต่อไปนี้

• create
• read
• run
• update
• download
• delete

ตัวอย่างเช่น ขอบเขตที่อนุญาตให้แอปพลิเคชันที่กำหนดเองเรียกใช้เมธอด อัปเดตแหล่งข้อมูล(ลิงก์จะเปิดในหน้าต่างใหม่) จะมีลักษณะ:

tableau:datasources:update

ประเภทขอบเขต

ประเภทของขอบเขตที่คุณใช้จะขึ้นอยู่กับเนื้อหาหรือการดำเนินการดูแลระบบที่คุณต้องการเปิดใช้งาน โดยทั่วไปแล้ว ขอบเขตจะจัดอยู่ในประเภทใดประเภทหนึ่งต่อไปนี้ ได้แก่ การอ่านเนื้อหา รายบุคคล ไวลด์การ์ด และข้ามหมวดหมู่

• ขอบเขตการอ่านเนื้อหา: ขอบเขตการอ่านเนื้อหา tableau:content:read จะเปิดใช้งานเมธอด GET ที่รองรับสำหรับเนื้อหาของ Tableau เมื่อคุณใช้ขอบเขตนี้ คุณจะเปิดใช้งานการดำเนินการข้ามหมวดหมู่ REST API หากกล่าวให้เฉพาะเจาะจงอย่างยิ่ง เมื่อใช้ขอบเขตนี้ คุณสามารถเปิดใช้งานเมธอด GET สำหรับแหล่งข้อมูล เมตริก มุมมอง เวิร์กบุ๊ก โปรเจ็กต์ และไซต์ได้ ตั้งแต่ Tableau Cloud ตุลาคม 2023 คุณยังระบุขอบเขตนี้ใน JWT ที่จะใช้เพื่อสร้างโทเค็นข้อมูลเข้าสู่ระบบเพื่อใช้กับ API เมตาดาต้า(ลิงก์จะเปิดในหน้าต่างใหม่)อีกด้วย

  หมายเหตุ: หากต้องการเปิดใช้งานเมธอด GET สำหรับการดำเนินการดูแลระบบ เช่น ผู้ใช้และกลุ่ม คุณสามารถใช้ขอบเขตรายบุคคลได้

• ขอบเขตรายบุคคล: หากต้องการเปิดใช้งานเนื้อหาและการดำเนินการดูแลระบบที่รองรับ คุณสามารถใช้ขอบเขตรายบุคคลได้ โดยทั่วไปแล้ว ขอบเขตรายบุคคลจะเชื่อมโยงกับเมธอดเดียวและหมวดหมู่ REST API

  ตัวอย่าง:

  • หากต้องการเปิดใช้การดำเนินการเผยแพร่หรืออัปเดตแหล่งข้อมูล คุณสามารถใช้ขอบเขตรายบุคคล tableau:datasources:create หรือ tableau:datasources:update ตามลำดับได้
  • สำหรับการดำเนินการดูแลระบบ เช่น เพิ่มหรือลบผู้ใช้ คุณสามารถใช้ขอบเขตรายบุคคลtableau:users:create หรือ tableau:users:delete ตามลำดับได้

  หมายเหตุ: มีขอบเขตรายบุคคลบางรายการที่สามารถเปิดใช้งานการดำเนินการข้ามหมวดหมู่ REST API ได้ ตัวอย่างเช่น tableau:views:download จะเปิดใช้งานการดำเนินการในหมวดหมู่ REST API ของข้อมูลมุมมองและเวิร์กบุ๊ก

• ขอบเขตไวลด์การ์ด: สำหรับบางขอบเขต คุณสามารถแทนที่การดำเนินการด้วยอักขระไวลด์การ์ด (*) เพื่อเปิดใช้งานการดำเนินการที่รองรับภายในหมวดหมู่ REST API ที่เฉพาะเจาะจงได้

  ตัวอย่าง:

  • คุณสามารถใช้ขอบเขตไวลด์การ์ด tableau:projects:* เพื่อเปิดใช้งานการสร้าง การลบ การอัปเดตการดำเนินการในหมวดหมู่ REST API ของโปรเจ็กต์ได้
  • คุณสามารถใช้ขอบเขตไวลด์การ์ด tableau:users:* เพื่อเปิดใช้งานการรับ/แสดงรายการ การเพิ่ม การลบ การอัปเดตการดำเนินการในหมวดหมู่ REST API ของผู้ใช้ได้
  • คุณสามารถใช้ขอบเขตไวลด์การ์ด tableau:tasks:* เพื่อเปิดใช้งานการรับ/แสดงรายการ การเพิ่ม การลบ การอัปเดต และการเรียกใช้การดำเนินการของหมวดหมู่ REST API สำหรับการแยกข้อมูลและการสมัครใช้บริการได้ นอกจากนี้ ขอบเขตนี้ยังเปิดใช้งานการอัปเดตแหล่งข้อมูล (หากแยก) และอัปเดตเวิร์กชีต

• ขอบเขตข้ามหมวดหมู่: นอกเหนือจากขอบเขตการอ่านเนื้อหาแล้ว ยังมีขอบเขตเพิ่มเติมอีกสองสามขอบเขตที่หากใช้ จะเปิดใช้งานการดำเนินการที่รองรับในหมวดหมู่ REST API ต่างๆ

  ตัวอย่าง:

  • ถ้าใช้ขอบเขต tableau:tasks:run คุณจะเปิดใช้งานการดำเนินการในหมวดหมู่ REST API ของแหล่งข้อมูลและเวิร์กบุ๊ก
  • ถ้าใช้ขอบเขต tableau:views:download คุณจะเปิดใช้งานการดำเนินการในหมวดหมู่ REST API ของมุมมองข้อมูลและเวิร์กบุ๊ก
  • ถ้าใช้ขอบเขตสิทธิ์ เช่น tableau:permissions:update หรือ tableau:permissions:delete คุณจะเปิดใช้งานการดำเนินการในหมวดหมู่ REST API ของแหล่งข้อมูล เวิร์กบุ๊ก และโปรเจ็กต์

สรุปของวิธีการอนุญาตการเข้าถึง REST API

รายการต่อไปนี้ให้สรุปขั้นตอนในการส่งคำขอการเข้าถึง REST API ผ่าน JWT:

1. สร้างแอปที่เชื่อมต่อp โดยใช้วิธีใดวิธีหนึ่งดังต่อไปนี้:
   • กำหนดค่าแอปที่เชื่อมต่อกับ Direct Trust
   • กำหนดค่าแอปที่เชื่อมต่อกับการพิทักษ์ OAuth 2.0
2. สร้าง JWT ที่ถูกต้อง—ที่รันไทม์ แอปพลิเคชันที่กำหนดเองของคุณจะสร้าง JWT ที่ถูกต้องซึ่งกำหนดค่าพร้อมกับขอบเขตที่คุณได้ใส่ไว้
3. สร้างคำขอเข้าสู่ระบบ(ลิงก์จะเปิดในหน้าต่างใหม่)—แอปพลิเคชันที่กำหนดเองของคุณจะสร้างคำขอ “เข้าสู่ระบบ” โดยใช้ JWT เพื่อส่งกลับโทเค็นข้อมูลเข้าสู่ระบบ Tableau และ ID ไซต์ (LUID)
4. ใช้โทเค็นการเข้าถึง Tableau ในคำขอต่อจากนั้น—ในการเรียกใช้ REST API ต่อจากนั้น ใช้ 1) โทเค็นข้อมูลเข้าสู่ระบบ Tableau เป็นค่าส่วนหัว X-Tableau-Auth(ลิงก์จะเปิดในหน้าต่างใหม่) และ 2) ID ไซต์ (LUID) ใน URI ของคำขอ

ตัวอย่าง

ตัวอย่างเช่น สมมติว่าคุณสร้างแอปที่เชื่อมต่อโดยใช้ Direct Trust โดยการใช้ Direct Trust แอปพลิเคชันที่กำหนดเองของคุณที่เรียกใช้ REST API จะสร้าง JWT ที่ถูกต้องโดยใช้ ID ไคลเอ็นต์และข้อมูลลับไคลเอ็นต์ที่สร้างโดยแอปที่เชื่อมต่อ

ขอบเขตใน JWT

เพื่ออนุญาตการเข้าถึง REST API ได้สำเร็จ JWT ยังจะต้องมีขอบเขตที่กำหนดความสามารถของ REST API ตัวอย่างเช่น เมื่อต้องการเปิดใช้งานเมธอดที่เกี่ยวข้องกับแหล่งข้อมูลหลายเมธอด คุณควรรวมขอบเขตต่อไปนี้ลงใน JWT:

"tableau:content:read","tableau:datasources:create","tableau:datasources:update","tableau:datasources:download","tableau:tasks:run"

หรือ

"tableau:content:read","tableau:datasources:*","tableau:tasks:run"

หมายเหตุ: ต้องส่งผ่านค่าขอบเขตเป็นประเภทรายการ

URI คำขอเข้าสู่ระบบ

ในการเรียกใช้ REST API แอปพลิเคชันที่กำหนดเองของคุณจะต้องส่งคำขอ “เข้าสู่ระบบ” เพื่อสร้างโทเค็นข้อมูลเข้าสู่ระบบ Tableau ก่อน

POST https://us-west-2b.online.tableau.com/api/3.16/auth/signin

เนื้อความของคำขอ

เพื่ออนุญาตการเข้าถึง REST API โดยใช้ JWT เนื้อความของคำขอเข้าสู่ระบบจะต้องมี JWT ที่ถูกต้องอย่างในตัวอย่างด้านล่าง

<tsRequest>
   <credentials jwt="eyJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJhbGciOiJIUzI1NiIsImtpZCI6ImIwMTE1YmY5LTNhNGItNGM5MS1iMDA5LWNmMGMxNzBiMWE1NiJ9.eyJhdWQiOiJ0YWJsZWF1Iiwic3ViIjoicm1vaGFuQHRhYmxlYXUuY29tIiwic2NwIjpbInRhYmxlYXU6c2l0ZXM6cmVhZCJdLCJpc3MiOiI4ZTFiNzE3Mi0zOWMzLTRhMzItODg3ZS1mYzJiNDExOWY1NmQiLCJleHAiOjE2NDg2Njg0MzksImp0aSI6IjY1ZWFmMmYxLTNmZTgtNDc5Ny1hZmRiLTMyODMzZDVmZGJkYSJ9.mUv2o4gtBTrMVLEXY5XTpzDQTGvfE2LGi-3O2vdGfT8">
    <site contentUrl="mycodotcom"/>
   </credentials>
</tsRequest>

เนื้อความการตอบกลับ

คำขอ “เข้าสู่ระบบ” จะสร้างเนื้อความการตอบกลับซึ่งรวมโทเค็นข้อมูลเข้าสู่ระบบ Tableau

<tsResponse>
   <credentials token="12ab34cd56ef78ab90cd12ef34ab56cd">
    <site id="9a8b7c6d5-e4f3-a2b1-c0d9-e8f7a6b5c4d" contentUrl=""/>
    <user id="9f9e9d9c-8b8a-8f8e-7d7c-7b7a6f6d6e6d" />
   </credentials>
</tsResponse>

หลังจากสร้างโทเค็นข้อมูลเข้าสู่ระบบ Tableau แล้ว ให้เพิ่มส่วนหัวของคำขอ REST API ที่ตามมาทั้งหมด

ส่วนหัว

X-Tableau-Auth:12ab34cd56ef78ab90cd12ef34ab56cd

คำขอ REST API ในภายหลังทั้งหมดที่ใช้โทเค็นการเข้าถึง Tableau จะถูกผูกโยงโดยขอบเขตใน JWT

เมธอด REST API ที่รองรับการรับรองสิทธิ์ของ JWT

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

หมายเหตุ:

• สำหรับความสามารถอื่นๆ ของ REST API ที่ไม่ได้แสดงไว้ในตารางด้านล่าง คุณสามารถใช้กลไกการรับรองสิทธิ์เพื่อเข้าถึงเมธอด หากต้องการข้อมูลเพิ่มเติม โปรดดูวิธีการรับรองสิทธิ์(ลิงก์จะเปิดในหน้าต่างใหม่)ในส่วนวิธีใช้ Tableau REST API
• รองรับทั้งวิธีการเข้าสู่ระบบ(ลิงก์จะเปิดในหน้าต่างใหม่)และออกจากระบบ(ลิงก์จะเปิดในหน้าต่างใหม่)โดยการให้สิทธิ์ JWT แต่ไม่กำหนดให้มีขอบเขตที่จะใช้ เริ่มตั้งแต่เดือนมิถุนายน 2023 (Tableau 2023.2)
• สำหรับขอบเขตที่รองรับโดย API ฝังตัว เวอร์ชัน 3 ให้ดูที่บทความหนึ่งใดต่อไปนี้:
  • กำหนดค่าแอปที่เชื่อมต่อกับ Direct Trust
  • กำหนดค่าแอปที่เชื่อมต่อกับการพิทักษ์ OAuth 2.0

ขอบเขตไวด์การ์ด (*)

ขอบเขตไวด์การ์ดใช้อักขระไวด์การ์ด (*) แทนการดำเนินการเฉพาะ เพื่อเปิดใช้งานการดำเนินการที่รองรับหลายรายการภายในหมวดหมู่ REST API ที่ระบุ ซึ่งรวมถึง:

ขอบเขตแบบข้ามหมวดหมู่

ขอบเขตแบบข้ามหมวดหมู่เปิดใช้งานการดำเนินการที่รองรับหลายรายการในหมวดหมู่ REST API หลายรายการ ซึ่งรวมถึง:

ขอบเขตรายบุคคล

แก้ปัญหาขอบเขต

401001 - ข้อผิดพลาดในการเข้าสู่ระบบ

หากคุณพบข้อผิดพลาด 401001 เนื้อหาการตอบกลับเข้าสู่ระบบจะถูกต่อท้ายด้วยรหัสข้อผิดพลาดเฉพาะแอปที่เชื่อมต่อเพิ่มเติมต่อไปนี้: 16, 10084 หรือ 10085

ตัวอย่างเช่น ในเนื้อหาการตอบกลับต่อไปนี้ "10084" คือรหัสข้อผิดพลาดของแอปที่เชื่อมต่อซึ่งคุณสามารถใช้เพื่อช่วยแก้ปัญหาเกี่ยวกับการเข้าสู่ระบบ Tableau Cloud โดยใช้ JWT สำหรับการตรวจสอบสิทธิ์ REST API

<error code="401001">  
  "summary": "Signin Error",
  "detail": "Error signing in to Tableau Cloud (10084)"
</error>

เพื่อช่วยแก้ไขปัญหา โปรดดูคำอธิบายของรหัสข้อผิดพลาดที่เกี่ยวข้องและสาเหตุที่เป็นไปได้

• 16: ไม่พบผู้ใช้ — ข้อผิดพลาดนี้อาจเกิดขึ้นได้เนื่องจาก "sub " ไม่ถูกต้อง (ชื่อผู้ใช้) ถูกระบุ

• 10084: ไม่สามารถแยกวิเคราะห์โทเค็นการเข้าถึง — ข้อผิดพลาดนี้อาจเกิดขึ้นได้จากสาเหตุต่อไปนี้:

  • JWT ไม่ถูกต้องหรือมีปัญหาที่ไม่คาดคิด
  • "aud " ไม่ถูกต้อง (กลุ่มเป้าหมาย) ถูกระบุ
  • เพื่อความไว้วางใจโดยตรง มีปัญหาในการลงนามข้อมูลลับ

• 10085: ไม่สามารถดึงข้อมูลลับเพื่อตรวจสอบลายเซ็นสำหรับ ID ไคลเอ็นต์ — ข้อผิดพลาดนี้อาจเกิดขึ้นได้จากสาเหตุต่อไปนี้:

  • ID ไคลเอ็นต์ไม่ถูกต้องใน "iss " ถูกระบุ
  • เพื่อความเชื่อถือโดยตรง "kid " ไม่ถูกต้อง (ID ข้อมูลลับ) ถูกระบุ
  • สำหรับ OAuth 2.0 trust ไม่สามารถดึงข้อมูลคีย์จาก JWKSource ได้

401002 - ข้อผิดพลาดการเข้าถึงที่ไม่ได้รับอนุญาต

หากคุณพบข้อผิดพลาด 401002 และยืนยันว่าคุณมีสิทธิ์ที่เหมาะสมในการส่งคำขอ ตรวจสอบให้แน่ใจว่าขอบเขตที่รวมอยู่ใน JWT นั้นถูกต้องและตรงกับคำขอที่คุณพยายามสร้าง สำหรับรายการปลายทางและขอบเขตที่รองรับ โปรดดูส่วนเมธอด REST API ที่รองรับการรับรองสิทธิ์ของ JWT ด้านบน