ร้องขอความยินยอมของผู้ใช้

สิ่งสำคัญ

ในเดือนมิถุนายน ค.ศ. 2022 เราได้แนะนํา การรับรองความถูกต้องแบบหลายปัจจัย เป็นข้อกําหนดสําหรับโฆษณา Bing คุณอาจยังจําเป็นต้องทําการเปลี่ยนแปลงรหัสเพื่อให้สอดคล้องกับข้อกําหนดนี้ Microsoft Advertising จะดําเนินการตรวจสอบการบังคับใช้ทางเทคนิคในช่วงต้นเดือนตุลาคม

โพสต์ในบล็อกนี้จะ สรุปขั้นตอนที่คุณควรดําเนินการเพื่อให้แน่ใจว่าเป็นไปตามข้อกําหนด

สําหรับข้อมูลเพิ่มเติม โปรดดูคําแนะนําข้อกําหนดในการรับรองความถูกต้องแบบหลายปัจจัย

เมื่อคุณลงทะเบียนแอปพลิเคชันแล้ว คุณจะต้องได้รับความยินยอมจากผู้ใช้เพื่อให้คุณจัดการบัญชี Microsoft Advertising ของพวกเขา

เคล็ดลับ

สําหรับความช่วยเหลือในการแก้ไขปัญหา ให้ดูคู่มือข้อผิดพลาด Common OAuth

สิ่งสำคัญ

ผู้ใช้แต่ละรายจะต้องได้รับพร้อมท์และให้ความยินยอมผ่านการควบคุมเว็บเบราว์เซอร์อย่างน้อยหนึ่งครั้งเพื่อให้แอปพลิเคชันของคุณจัดการบัญชี Microsoft Advertising ของพวกเขา นี่คือโฟลว์ OAuth 2.0 มาตรฐานและกําหนดไว้โดยละเอียดในส่วนการให้รหัสการให้สิทธิ์ของข้อมูลจําเพาะ OAuth 2.0

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

หมายเหตุ

แทนที่ your_client_id ด้านล่างด้วย ID แอปพลิเคชัน (ไคลเอ็นต์) ที่ พอร์ทัล Azure - พอร์ทัลการลงทะเบียนแอป ที่กําหนดให้กับแอปของคุณ

// Line breaks for legibility only

https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id=your_client_id
&response_type=code
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&response_mode=query
&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&state=12345

1. คัดลอก URL ด้านล่างและวางลงในเบราว์เซอร์ของคุณเพื่อดําเนินการร้องขอตัวอย่างนี้เพื่อขอความยินยอมจากผู้ใช้

หมายเหตุ

แทนที่ your_client_id ใน URL ด้านล่างด้วย ID แอปพลิเคชัน (ไคลเอ็นต์) ที่ พอร์ทัล Azure - พอร์ทัลการลงทะเบียนแอป ที่กําหนดให้กับแอปของคุณ

<https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=your_client_id&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F&response_mode=query&scope=openid%20offline_access%20https%3A%2F%2Fads.microsoft.com%2Fmsads.manage&state=12345>

1. ลงชื่อเข้าใช้ด้วยข้อมูลประจําตัวบัญชี Microsoft ของคุณและให้ความยินยอม ของแอปเพื่อ จัดการบัญชี Microsoft Advertising ของคุณ
2. หลังจากลงชื่อเข้าใช้ แล้ว เบราว์เซอร์ของคุณควรเปลี่ยนเส้นทางไปยัง https://localhost/myapp/ ด้วย code ในแถบที่อยู่ คุณสามารถละเว้นข้อความแสดงข้อผิดพลาดบนหน้าได้
3. ถัดไป คุณจะใช้รหัสเพื่อรับโทเค็นการเข้าถึงและการรีเฟรช

ปลายทางแพลตฟอร์มข้อมูลประจำตัวของ Microsoft ยังช่วยให้มั่นใจว่าผู้ใช้ได้ยินยอมให้สิทธิที่ระบุไว้ในscopeพารามิเตอร์คิวรี ถ้าผู้ใช้ไม่ได้ยินยอมให้เข้าถึงสิทธิ์ใดๆ เหล่านั้น ผู้ใช้จะขอให้ผู้ใช้ยินยอมให้มีสิทธิ์ที่จําเป็น แม้ว่าคู่มือนี้จะมุ่งเน้นไปที่การจัดการบัญชี Microsoft Advertising เป็นหลักผ่าน scope=https://ads.microsoft.com/msads.manageรายละเอียดเพิ่มเติมเกี่ยวกับสิทธิ์และความยินยอมในแพลตฟอร์มข้อมูลประจำตัวของ Microsoft มีให้ที่นี่

เมื่อผู้ใช้รับรองความถูกต้องและให้ความยินยอม จุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft จะส่งกลับการตอบสนองไปยังแอปของคุณใน ที่ระบุ redirect_uriโดยใช้วิธีการที่ระบุในresponse_modeพารามิเตอร์ ตัวอย่างเช่น URI เรียกกลับประกอบด้วยรหัสการให้สิทธิ์ดังนี้ถ้าผู้ใช้ให้สิทธิ์สําหรับแอปพลิเคชันของคุณในการจัดการบัญชี Microsoft Advertising ของพวกเขา: http://localhost/myapp/?code=CodeGoesHere& state=12345.

หากผู้ใช้ให้สิทธิ์แอปพลิเคชันของคุณในการจัดการบัญชี Microsoft Advertising คุณควรใช้รหัสทันทีในขั้นตอนถัดไป ระยะเวลาสั้น ๆ ของรหัสการให้สิทธิ์ประมาณ 5 นาทีอาจเปลี่ยนแปลงได้ ถ้าผู้ใช้ปฏิเสธสิทธิ์แอปพลิเคชันของคุณในการจัดการบัญชี Microsoft Advertising URI เรียกกลับจะมีข้อผิดพลาดและเขตข้อมูลคําอธิบายข้อผิดพลาดดังนี้: http://localhost/myapp/?error=access_denied& error_description=สถานะ ERROR_DESCRIPTION&=ClientStateGoesHere สําหรับรายละเอียดเพิ่มเติมเกี่ยวกับข้อผิดพลาด OAuth โปรดดู ข้อผิดพลาดทั่วไปของ OAuth และ รหัสข้อผิดพลาดการรับรองความถูกต้องและการรับรองความถูกต้อง

ตารางต่อไปนี้ประกอบด้วยพารามิเตอร์ที่ไคลเอ็นต์ API โฆษณา Bing สามารถรวมไว้ในคําขอความยินยอมได้ สําหรับรายละเอียดเพิ่มเติมเกี่ยวกับพารามิเตอร์ทางเลือก ให้ดูเอกสารประกอบโฟลว์รหัสการให้สิทธิ์ แพลตฟอร์มข้อมูลประจำตัวของ Microsoft OAuth 2.0

พารามิเตอร์	จําเป็น/ไม่บังคับ	คำอธิบาย
client_id	ต้องระบุ	ID แอปพลิเคชัน (ไคลเอ็นต์) ที่ พอร์ทัล Azure - พอร์ทัลการลงทะเบียนแอป กําหนดแอปของคุณ
code_challenge	แนะ นำ	ใช้เพื่อรักษาความปลอดภัยการให้รหัสการให้สิทธิ์ผ่าน Proof Key สําหรับ Code Exchange (PKCE) จําเป็นถ้า code_challenge_method รวมอยู่ด้วย สําหรับข้อมูลเพิ่มเติม โปรดดู PKCE RFC ตอนนี้เราขอแนะนําสําหรับแอปพลิเคชันทุกประเภท - แอปดั้งเดิม, SPAs และไคลเอ็นต์ที่เป็นความลับ เช่น เว็บแอป
code_challenge_method	แนะ นำ	เมธอดที่ใช้ในการเข้ารหัส code_verifier สําหรับ code_challenge พารามิเตอร์ สามารถเป็นหนึ่งในค่าต่อไปนี้: - plain - S256 ถ้าไม่รวม code_challenge จะสันนิษฐานว่าเป็นข้อความธรรมดาถ้ามีcode_challenge แพลตฟอร์มข้อมูลประจำตัวของ Microsoft สนับสนุนทั้ง plain และS256 สําหรับข้อมูลเพิ่มเติม โปรดดู PKCE RFC
prompt	เสริม	ระบุชนิดของการโต้ตอบของผู้ใช้ที่แอปพลิเคชันของคุณต้องการ ค่าที่ได้รับการสนับสนุนมีดังต่อไปนี้: - prompt=login จะบังคับให้ผู้ใช้ใส่ข้อมูลประจําตัวของตนในคําขอดังกล่าว โดยจะลบการลงชื่อเข้าระบบครั้งเดียว - prompt=none ซึ่งตรงข้ามกับ "login" เช่น จะทําให้แน่ใจว่าผู้ใช้จะไม่แสดงพร้อมท์แบบโต้ตอบใด ๆ ถ้าไม่สามารถดําเนินการคําขอให้เสร็จสมบูรณ์ได้แบบเงียบๆ ผ่านการลงชื่อเข้าระบบครั้งเดียว จุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft จะส่งกลับข้อผิดพลาด interaction_required - prompt=consent จะทริกเกอร์กล่องโต้ตอบความยินยอม OAuth หลังจากผู้ใช้ลงชื่อเข้าใช้ เพื่อขอให้ผู้ใช้ให้สิทธิ์แก่แอป - prompt=select_account จะขัดจังหวะการลงชื่อเข้าระบบครั้งเดียวและมอบประสบการณ์การเลือกบัญชี แสดงรายการบัญชีทั้งหมดในเซสชันหรือบัญชีที่ถูกจดจําไว้ หรือตัวเลือกให้เลือกใช้บัญชีอื่นทั้งหมด
redirect_uri	ต้องระบุ	redirect_uri ของแอปของคุณ ที่แอปของคุณสามารถส่งและรับการตอบสนองการรับรองความถูกต้องได้ ซึ่งจะต้องตรงกับหนึ่งใน redirect_uris ที่คุณลงทะเบียนไว้ในพอร์ทัล เว้นแต่จะต้องเข้ารหัส URL ไว้ สําหรับแอป & ดั้งเดิมสําหรับอุปกรณ์เคลื่อนที่ คุณควรใช้ค่าเริ่มต้นของhttps://login.microsoftonline.com/common/oauth2/nativeclient
response_mode	แนะ นำ	ระบุวิธีการที่ควรใช้เพื่อส่งโทเค็นผลลัพธ์กลับไปยังแอปของคุณ อาจเป็นรายการใดรายการหนึ่งต่อไปนี้: - query - fragment - form_post query ให้โค้ดเป็นพารามิเตอร์สตริงคิวรีบน URI เปลี่ยนเส้นทางของคุณ ถ้าคุณกําลังร้องขอโทเค็น ID โดยใช้โฟลว์โดยนัย คุณจะไม่สามารถใช้ query ตามที่ระบุใน ข้อมูลจําเพาะ OpenID ได้ ถ้าคุณกําลังร้องขอเพียงรหัส คุณสามารถใช้ query, fragmentหรือ form_postได้ form_post ดําเนินการ POST ที่มีรหัสไปยัง URI การเปลี่ยนเส้นทางของคุณ สําหรับข้อมูลเพิ่มเติม ดูโพรโทคอล OpenID Connect
response_type	ต้องระบุ	ต้องรวม code สําหรับโฟลว์รหัสการตรวจสอบ
scope	ต้องระบุ	รายการ ขอบเขต ที่คั่นด้วยช่องว่างที่คุณต้องการให้ผู้ใช้ยินยอม ตรวจสอบให้แน่ใจว่าได้รวม https://ads.microsoft.com/msads.manage ไว้เพื่อพร้อมท์ผู้ใช้สําหรับการเข้าถึง Microsoft Advertising รวม offline_access เพื่อให้แน่ใจว่าโทเค็นรีเฟรชรวมอยู่ในการตอบสนอง
state	แนะ นำ	ค่าที่รวมอยู่ในคําขอที่จะถูกส่งกลับในการตอบสนองโทเค็นด้วย ซึ่งอาจเป็นสตริงของเนื้อหาใด ๆ ที่คุณต้องการ โดยทั่วไปค่าที่ไม่ซ้ํากันที่สร้างขึ้นแบบสุ่มจะใช้เพื่อป้องกันการโจมตีของปลอมคําขอข้ามไซต์ ค่านี้ยังสามารถเข้ารหัสข้อมูลเกี่ยวกับสถานะของผู้ใช้ในแอปก่อนที่การร้องขอการรับรองความถูกต้องจะเกิดขึ้น เช่น หน้า หรือมุมมองที่ผู้ใช้อยู่
tenant	ต้องระบุ	{tenant}ค่าในเส้นทางของคําขอสามารถใช้เพื่อควบคุมว่าใครสามารถลงชื่อเข้าใช้แอปพลิเคชันได้ เพื่อให้แน่ใจว่าแอปพลิเคชันของคุณสนับสนุนทั้งบัญชีส่วนบุคคล MSA และบัญชีที่ทํางานหรือโรงเรียน Azure AD เราขอแนะนําให้คุณใช้commonเป็นผู้เช่าสําหรับการรับรองความถูกต้อง Bing Ads API ในกรณีที่แอปพลิเคชันของคุณต้องการผู้เช่าอื่น โปรดดูจุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft สําหรับข้อมูลเพิ่มเติม

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

รับโทเค็นการเข้าถึงและการรีเฟรช

ดูเพิ่มเติม

เริ่มต้นใช้งาน