แชร์ผ่าน

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

  • บทความ

สิ่งสำคัญ

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

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

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

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

  1. ร้องขอโทเค็นการเข้าถึงโดยแลกรับข้อมูลที่codeส่งกลับหลังจากที่ผู้ใช้ได้รับความยินยอม รับ ค่า access_tokenrefresh_token และ expires_in จากสตรีมการตอบสนอง JSON
  2. เมื่อคุณได้รับโทเค็นการเข้าถึง ค่าของ expires_in จะแสดงเวลาสูงสุดเป็นวินาที จนกว่าโทเค็นการเข้าถึงจะหมดอายุ ก่อนที่โทเค็นการเข้าถึงจะหมดอายุหรือก่อนที่คุณจะต้องเข้าถึง API อีกครั้ง คุณควรรีเฟรชโทเค็นการเข้าถึง
  3. เมื่อคุณได้รับ access_tokenสําเร็จ คุณสามารถใช้โทเค็นในคําขอไปยัง Bing Ads API ได้ ดูคําแนะนํา การโทร API แรกของคุณ สําหรับตัวอย่าง

นี่คือตัวอย่างของขั้นตอนที่ 1 และ 2 ด้านบน

หมายเหตุ

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

# Replace your_client_id with your registered application ID. 
$clientId = "your_client_id"

Start-Process "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=$clientId&scope=openid%20profile%20https://ads.microsoft.com/msads.manage%20offline_access&response_type=code&redirect_uri=https://login.microsoftonline.com/common/oauth2/nativeclient&state=ClientStateGoesHere&prompt=login"

$code = Read-Host "Grant consent in the browser, and then enter the response URI here:"
$code = $code -match 'code=(.*)\&'
$code = $Matches[1]

# Get the initial access and refresh tokens. 

$response = Invoke-WebRequest https://login.microsoftonline.com/common/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://ads.microsoft.com/msads.manage%20offline_access&code=$code&grant_type=authorization_code&redirect_uri=https%3A%2F%2Flogin.microsoftonline.com%2Fcommon%2Foauth2%2Fnativeclient"

$oauthTokens = ($response.Content | ConvertFrom-Json)  
Write-Output "Access token: " $oauthTokens.access_token  
Write-Output "Access token expires in: " $oauthTokens.expires_in  
Write-Output "Refresh token: " $oauthTokens.refresh_token 

# The access token will expire e.g., after one hour. 
# Use the refresh token to get new access and refresh tokens. 

$response = Invoke-WebRequest https://login.microsoftonline.com/common/oauth2/v2.0/token -ContentType application/x-www-form-urlencoded -Method POST -Body "client_id=$clientId&scope=https://ads.microsoft.com/msads.manage%20offline_access&code=$code&grant_type=refresh_token&refresh_token=$($oauthTokens.refresh_token)"

$oauthTokens = ($response.Content | ConvertFrom-Json)  
Write-Output "Access token: " $oauthTokens.access_token  
Write-Output "Access token expires in: " $oauthTokens.expires_in  
Write-Output "Refresh token: " $oauthTokens.refresh_token

เคล็ดลับ

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

รายละเอียดการร้องขอโทเค็นการเข้าถึง

คุณสามารถแลก ใช้ code สําหรับ access_token ไปยังทรัพยากรที่ต้องการได้ ทําสิ่งนี้โดยการส่ง POST คําขอไปยัง /token จุดสิ้นสุด:

หมายเหตุ

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

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri=http%3A%2F%2Flocalhost%2Fmyapp%2F
&grant_type=authorization_code
&client_secret=JqQX2PNo9bpM0uEihUPzyrh    // NOTE: Only applicable for web apps

เนื้อความของการร้องขอต้องมีพารามิเตอร์การร้องขอและส่วนหัว Content-Type ต้องถูกตั้งค่าเป็น application/x-www-form-urlencoded ตั้งค่าพารามิเตอร์รหัสเป็นค่าของรหัสการตรวจสอบที่ดึงข้อมูลในขั้นตอนก่อนหน้า และชนิดเงินช่วยเหลือที่ตั้งค่าเป็น authorization_code redirect_uri ต้องตรงกับ URI การเปลี่ยนเส้นทางที่ใช้เพื่อรับรหัสการตรวจสอบ ตรวจสอบให้แน่ใจว่าได้เข้ารหัส URL เปลี่ยนเส้นทางแล้ว ถ้าคุณลงทะเบียนแอปพลิเคชันบนเว็บ ให้รวมพารามิเตอร์ client_secret และตั้งค่าเป็นค่าที่เตรียมใช้งานในลงทะเบียนแอปพลิเคชัน

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

พารามิเตอร์ จําเป็น/ไม่บังคับ คำอธิบาย
client_id ต้องระบุ ID แอปพลิเคชัน (ไคลเอ็นต์) ที่ พอร์ทัล Azure - พอร์ทัลการลงทะเบียนแอป กําหนดแอปของคุณ
client_secret จําเป็นสําหรับเว็บแอป ข้อมูลลับของแอปพลิเคชันที่คุณสร้างขึ้นในพอร์ทัลการลงทะเบียนแอปสําหรับแอปของคุณ ไม่ควรใช้ในแอปดั้งเดิมเนื่องจาก client_secrets ไม่สามารถจัดเก็บไว้บนอุปกรณ์ได้อย่างน่าเชื่อถือ ซึ่งจําเป็นสําหรับเว็บแอปและ API ของเว็บ ซึ่งมีความสามารถในการจัดเก็บ client_secret ไว้อย่างปลอดภัยบนฝั่งเซิร์ฟเวอร์ ข้อมูลลับของไคลเอ็นต์ต้องเข้ารหัส URL ก่อนที่จะส่ง
code ต้องระบุ authorization_code ที่คุณได้รับเป็นผลมาจากการร้องขอความยินยอมของผู้ใช้
code_verifier แนะ นำ code_verifier เดียวกันกับที่ใช้ในการขอรับ authorization_code จําเป็นถ้ามีการใช้ PKCE ในคําขอการให้สิทธิ์รหัสการตรวจสอบ สําหรับข้อมูลเพิ่มเติม โปรดดู PKCE RFC
grant_type ต้องระบุ ต้องใช้สําหรับ authorization_code โฟลว์รหัสการให้สิทธิ์
redirect_uri ต้องระบุ ค่า redirect_uri เดียวกับที่ใช้เพื่อรับ authorization_code
scope ต้องระบุ รายการขอบเขตที่คั่นด้วยช่องว่าง ขอบเขตที่ร้องขอในขานี้ต้องเทียบเท่ากับหรือชุดย่อยของขอบเขตที่รวมอยู่เมื่อคุณร้องขอความยินยอมของผู้ใช้ ถ้าขอบเขตที่ระบุในการร้องขอนี้ครอบคลุมหลายเซิร์ฟเวอร์ทรัพยากร จุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft จะส่งกลับโทเค็นสําหรับทรัพยากรที่ระบุในขอบเขตแรก สําหรับคําอธิบายขอบเขตโดยละเอียดเพิ่มเติม โปรดดูที่สิทธิ์ ความยินยอม และขอบเขต
tenant ต้องระบุ {tenant}ค่าในเส้นทางของคําขอสามารถใช้เพื่อควบคุมว่าใครสามารถลงชื่อเข้าใช้แอปพลิเคชันได้ เพื่อให้แน่ใจว่าแอปพลิเคชันของคุณสนับสนุนทั้งบัญชีส่วนบุคคล MSA และบัญชีที่ทํางานหรือโรงเรียน Azure AD เราขอแนะนําให้คุณใช้commonเป็นผู้เช่าสําหรับการรับรองความถูกต้อง Bing Ads API

ในกรณีที่แอปพลิเคชันของคุณต้องการผู้เช่าอื่น โปรดดูจุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft สําหรับข้อมูลเพิ่มเติม

รีเฟรชรายละเอียดการร้องขอโทเค็น

โทเค็นการเข้าถึงจะเป็นแบบสั้น และคุณต้องรีเฟรชโทเค็นเหล่านั้นหลังจากที่หมดอายุเพื่อเข้าถึงทรัพยากรต่อไป คุณสามารถทําได้โดยการส่งคําขออื่นPOSTไปยัง/tokenปลายทาง คราวนี้ให้ refresh_token แทนcode โทเค็นรีเฟรชจะใช้ได้สําหรับสิทธิ์ทั้งหมดที่ไคลเอ็นต์ของคุณได้รับความยินยอมแล้ว

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

หมายเหตุ

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

// Line breaks for legibility only

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id
&scope=https%3A%2F%2Fads.microsoft.com%2Fmsads.manage
&refresh_token=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq...
&grant_type=refresh_token
&client_secret=JqQX2PNo9bpM0uEihUPzyrh      // NOTE: Only applicable for web apps

เนื้อความของการร้องขอต้องมีพารามิเตอร์การร้องขอและส่วนหัว Content-Type ต้องถูกตั้งค่าเป็น application/x-www-form-urlencoded ตั้งค่าพารามิเตอร์โทเค็นรีเฟรชเป็นค่าของโทเค็นรีเฟรชที่ดึงมาในขั้นตอนก่อนหน้า และชนิดเงินช่วยเหลือที่ตั้งค่าเป็น refresh_token ถ้าคุณลงทะเบียนแอปพลิเคชันบนเว็บ ให้รวมพารามิเตอร์ client_secret และตั้งค่าเป็นค่าที่เตรียมใช้งานในลงทะเบียนแอปพลิเคชัน

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

พารามิเตอร์ จําเป็น/ไม่บังคับ คำอธิบาย
client_id ต้องระบุ ID แอปพลิเคชัน (ไคลเอ็นต์) ที่ พอร์ทัล Azure - พอร์ทัลการลงทะเบียนแอป กําหนดแอปของคุณ
client_secret จําเป็นสําหรับเว็บแอป ข้อมูลลับของแอปพลิเคชันที่คุณสร้างขึ้นในพอร์ทัลการลงทะเบียนแอปสําหรับแอปของคุณ ไม่ควรใช้ในแอปดั้งเดิมเนื่องจาก client_secrets ไม่สามารถจัดเก็บไว้บนอุปกรณ์ได้อย่างน่าเชื่อถือ ซึ่งจําเป็นสําหรับเว็บแอปและ API ของเว็บ ซึ่งมีความสามารถในการจัดเก็บ client_secret ไว้อย่างปลอดภัยบนฝั่งเซิร์ฟเวอร์
grant_type ต้องระบุ ต้องตั้งค่าเป็น refresh_token สําหรับโฟลว์รหัสการให้สิทธิ์นี้
refresh_token ต้องระบุ refresh_token ที่คุณได้รับเมื่อคุณร้องขอโทเค็นการเข้าถึง
scope ต้องระบุ รายการขอบเขตที่คั่นด้วยช่องว่าง ขอบเขตที่ร้องขอในขานี้ต้องเทียบเท่ากับหรือชุดย่อยของขอบเขตที่รวมอยู่เมื่อคุณร้องขอความยินยอมของผู้ใช้ ถ้าขอบเขตที่ระบุในการร้องขอนี้ครอบคลุมหลายเซิร์ฟเวอร์ทรัพยากร จุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft จะส่งกลับโทเค็นสําหรับทรัพยากรที่ระบุในขอบเขตแรก สําหรับคําอธิบายขอบเขตโดยละเอียดเพิ่มเติม โปรดดูที่สิทธิ์ ความยินยอม และขอบเขต
tenant ต้องระบุ {tenant}ค่าในเส้นทางของคําขอสามารถใช้เพื่อควบคุมว่าใครสามารถลงชื่อเข้าใช้แอปพลิเคชันได้ เพื่อให้แน่ใจว่าแอปพลิเคชันของคุณสนับสนุนทั้งบัญชีส่วนบุคคล MSA และบัญชีที่ทํางานหรือโรงเรียน Azure AD เราขอแนะนําให้คุณใช้commonเป็นผู้เช่าสําหรับการรับรองความถูกต้อง Bing Ads API

ในกรณีที่แอปพลิเคชันของคุณต้องการผู้เช่าอื่น โปรดดูจุดสิ้นสุดแพลตฟอร์มข้อมูลประจำตัวของ Microsoft สําหรับข้อมูลเพิ่มเติม

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

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

{"error":"invalid_grant","error_description":"The user could not be authenticated or the grant is expired. The user must first sign in and if needed grant the client application access to the requested scope."}

โปรดทราบว่าโทเค็นรีเฟรชสาธารณะจะผูกกับอุปกรณ์ที่ได้รับสิทธิ์เท่านั้น ตัวอย่างเช่น ถ้าคุณลงทะเบียนแอปแบบดั้งเดิมและใช้ https://login.microsoftonline.com/common/oauth2/nativeclient เป็น URI เปลี่ยนเส้นทาง เรารับประกันว่าสามารถรีเฟรชได้บนอุปกรณ์เดียวกันเท่านั้น ไคลเอ็นต์ที่เรียกใช้แอปบนบริการที่ครอบคลุมภูมิภาคและอุปกรณ์ เช่น Microsoft Azure ควรลงทะเบียนเว็บแอปด้วยข้อมูลลับของไคลเอ็นต์ URI เปลี่ยนเส้นทางสามารถเป็น localhost ได้ แต่ไม่สามารถhttps://login.microsoftonline.com/common/oauth2/nativeclient ถ้าคุณใช้กับ https://login.microsoftonline.com/common/oauth2/nativeclient ข้อมูลลับไคลเอ็นต์ ข้อผิดพลาดต่อไปนี้จะถูกส่งกลับ

{"error":"invalid_request","error_description":"Public clients can't send a client secret."} Likewise for Web apps please note that refresh tokens can be invalidated at any moment.

คุณจะพบข้อผิดพลาดเดียวกันถ้าคุณพยายามร้องขอโทเค็นการเข้าถึงและการรีเฟรชใหม่โดยใช้โทเค็นรีเฟรชที่เตรียมใช้งานโดยไม่มีความลับของไคลเอ็นต์

สําหรับรายละเอียดเพิ่มเติมเกี่ยวกับข้อผิดพลาด OAuth โปรดดู ข้อผิดพลาดทั่วไปของ OAuth และ รหัสข้อผิดพลาดการรับรองความถูกต้องและการรับรองความถูกต้อง

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

ทําการเรียก API แรกของคุณ

ดูเพิ่มเติม

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