Cài đặt ứng dụng, tạo, làm mới và thu hồi mã

Vì biểu thị lệnh gọi máy chủ nên người dùng hệ thống không có phương thức Đăng nhập bằng Facebook và không thể cài đặt ứng dụng hoặc thực hiện quy trình oAuth tiêu chuẩn của Facebook để tạo mã. Bạn cần thực hiện việc này qua lệnh gọi API.

Các loại mã truy cập hệ thống

Loại	Mã truy cập không hết hạn	Mã truy cập có hết hạn được gợi ý
Trọn đời	Không bao giờ hết hạn	Có hiệu lực trong 60 ngày
Cần làm mới?	Không	Có
Đề xuất dựa trên trường hợp sử dụng	Bạn có thể chấp nhận rủi ro bị rò rỉ mã truy cập và muốn các ứng dụng bên thứ ba của mình có quyền truy cập offline vào dữ liệu.	Bạn muốn hạn chế rủi ro bị rò rỉ mã truy cập.

Cài đặt ứng dụng

Người dùng hệ thống hoặc người dùng hệ thống là quản trị viên phải cài đặt ứng dụng sẽ được dùng để tạo mã truy cập. Điều đó có nghĩa là cho phép ứng dụng gọi API thay cho người dùng hệ thống hoặc người dùng hệ thống là quản trị viên này.

Cả người dùng hệ thống và ứng dụng đều thuộc về một Trình quản lý kinh doanh. Bạn chỉ có thể cài đặt những ứng dụng có quyền truy cập tiêu chuẩn trở lên của API Quản lý quảng cáo.

Để cài đặt ứng dụng cho người dùng hệ thống, bạn cần có:

access_token: của người dùng quản trị viên, người dùng hệ thống là quản trị viên hoặc người dùng hệ thống khác
business_app: ID của ứng dụng đang được cài đặt

Để cài đặt ứng dụng cho người dùng hệ thống, hãy gửi yêu cầu POST:

curl \
-F "business_app=APP-ID" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/applications"

Lệnh gọi này trả về kết quả boolean nếu quá trình cài đặt thành công. Nếu không đáp ứng bất kỳ hạn chế nào, bạn sẽ thấy một thông báo lỗi tương ứng.

Tạo mã truy cập

Sau khi đã cài đặt ứng dụng, người dùng hệ thống có thể tạo mã truy cập dài hạn. Một số hạn chế sẽ được áp dụng:

Người dùng hệ thống phải cài đặt ứng dụng được đưa vào thông số, như ở bước trên.
Ứng dụng chỉ có thể nhắm mục tiêu những doanh nghiệp (hoặc doanh nghiệp con của những doanh nghiệp này) đã xác nhận ứng dụng.
Người dùng hệ thống và chủ sở hữu của mã truy cập được dùng trong lệnh gọi API tạo mã này phải thuộc về cùng một Trình quản lý kinh doanh.
Ứng dụng có thể thuộc hoặc không thuộc sở hữu của Trình quản lý kinh doanh đó. Nếu không, một số hạn chế sẽ được áp dụng. Hãy xem phần bên dưới.

Sau đây là các thông số của lệnh gọi API:

business_app: ứng dụng thuộc sở hữu của Trình quản lý kinh doanh chứa người dùng hệ thống.
appsecret_proof: trường đã tính toán của ứng dụng. Đây là trường bắt buộc để đảm bảo rằng máy chủ phù hợp đang thực hiện lệnh gọi API. Để biết thêm thông tin chi tiết, hãy xem lại tài liệu Bảo mật đăng nhập.
scope: chuỗi chứa các quyền mở rộng được phân tách bằng dấu phẩy.
access_token: mã của quản trị viên Trình quản lý kinh doanh, người dùng hệ thống là quản trị viên hoặc người dùng hệ thống thông thường.
set_token_expires_in_60_days: đặt là true để tạo một mã truy cập có hết hạn dành cho người dùng hệ thống. Không bắt buộc.

Các phạm vi được hỗ trợ cho người dùng hệ thống:

ads_management
ads_read
attribution_read
business_management
catalog_management
commerce_account_manage_orders
commerce_account_read_orders
commerce_account_read_settings
instagram_basic
instagram_branded_content_ads_brand
instagram_branded_content_brand
instagram_content_publish
instagram_manage_comments
instagram_manage_insights
instagram_manage_messages
instagram_shopping_tag_products
leads_retrieval
page_events
pages_manage_ads
pages_manage_cta
pages_manage_engagement
pages_manage_instant_articles
pages_manage_metadata
pages_manage_posts
pages_messaging
pages_read_engagement
pages_read_user_content
pages_show_list
private_computation_access
publish_video
read_audience_network_insights
read_insights
read_page_mailboxes
whatsapp_business_management
whatsapp_business_messaging

Quyền không dùng nữa, chỉ hiển thị cho các ứng dụng được tạo trước ngày 24/04/2018

publish_actions

Quyền bị kiểm soát truy cập theo tính năng

Tính năng	Quyền
business_creative_asset_management	`business_creative_managementbusiness_creative_insights` `business_creative_insights_sharebusiness_data_management`
commerce_public_api_beta_testing	`commerce_manage_accountscommerce_account_read_reports`

Để tạo appsecret_proof, bạn có thể sử dụng mã PHP:

$appsecret_proof = hash_hmac(
  'sha256',
  $access_token_used_in_the_call,
  $app_secret_for_the_app_used_in_the_call,
);

Trong mã mẫu ở trên, app_secret_for_the_app_used_in_the_call là khóa bí mật của ứng dụng được dùng để tạo mã truy cập. Bạn có thể tìm khóa bí mật của ứng dụng trong Bảng điều khiển ứng dụng.

appsecret_proof được băm sẽ là một chuỗi có dạng "1734d0d1e1ca62c9762c10bbc7321fdf89ecc7d819312b2f3".

Để tạo mã truy cập vĩnh viễn dành cho người dùng hệ thống, hãy gửi yêu cầu POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Để tạo mã truy cập có hết hạn dành cho người dùng hệ thống, hãy gửi yêu cầu POST:

curl \
-F "business_app=<APP_ID>" \
-F "scope=ads_management,manage_pages" \
-F "set_token_expires_in_60_days=true" \
-F "appsecret_proof=APPSECRET-PROOF" \
-F "access_token=ACCESS-TOKEN" \
"https://graph.facebook.com/API-VERSION/SYSTEM-USER-ID/access_tokens"

Trước đây, điểm cuối có tên là /SYSTEM-USER-ID/ads_access_token. Lệnh gọi đến tên này không còn hoạt động.

Hệ thống sẽ trả về chuỗi mã truy cập. Nếu không đáp ứng bất kỳ hạn chế nào, bạn sẽ thấy mã lỗi tương ứng. Phản hồi:

{
  "access_token": "CAAB3rQQzTFABANaYYCmOuLhbC]Fu8cAnmkcvT0ZBIDNm1d1fSp4Eg4XA79gmYumZCoSuiMSUILUjzG3y15BJlrYwXdqwd5c7y3lOUzu6aT7MkXL6HpISksSuLP4aFKWPmwb6iOgGeugRSn766xMZCN72vTiGGLUNqC2MKRL"
}

Bạn cũng có thể tạo Mã truy cập dành cho người dùng hệ thống qua giao diện người dùng Trình quản lý kinh doanh.

Làm mới mã truy cập

Mã có hết hạn dành cho người dùng hệ thống có hiệu lực trong 60 ngày kể từ ngày tạo hoặc ngày làm mới. Để tạo tính liên tục, nhà phát triển phải làm mới mã truy cập này trong vòng 60 ngày. Nếu không, mã truy cập nêu trên sẽ bị mất và nhà phát triển phải lấy một mã mới để lấy lại quyền truy cập API.

Để làm mới một mã truy cập có hết hạn dành cho người dùng hệ thống, bạn cần có:

fb_exchange_token: Mã truy cập hợp lệ dành cho người dùng hệ thống
client_id: ID ứng dụng
client_secret: Khóa bí mật của ứng dụng
set_token_expires_in_60_days: đặt là true để làm mới mã truy cập có hết hạn dành cho người dùng hệ thống.

Truy vấn điểm cuối GET oauth/access_token.

Yêu cầu mẫu

curl -i -X GET 
"https://graph.facebook.com/{graph-api-version}/oauth/access_token?  
    grant_type=fb_exchange_token&          
    client_id={app-id}&
    client_secret={app-secret}&
    set_token_expires_in_60_days=true&
    fb_exchange_token={your-access-token}"

Phản hồi mẫu

{
  "access_token":"{expiring-system-user-access-token}",
  "token_type": "bearer",
  "expires_in": 5183944    // Time left in seconds until the token expires
}

Thu hồi mã truy cập

Điểm cuối này dùng để xoay vòng mã thông thường hoặc thu hồi mã truy cập của người dùng hệ thống bị xâm phạm nhằm bảo vệ hệ thống của bạn.

Để thu hồi một mã truy cập dành cho người dùng hệ thống, bạn cần có:

revoke_token: Mã truy cập để thu hồi
client_id: ID ứng dụng
client_secret: Khóa bí mật của ứng dụng
access_token: Mã truy cập để xác định người gọi

Dưới đây là các yêu cầu:

client_id phải tương ứng với ứng dụng thực tế và đảm bảo rằng ứng dụng này không bị giới hạn tốc độ, vô hiệu hóa hoặc xóa.
client_id, cùng với ứng dụng đã cài đặt của revoke_token, ứng dụng đã cài đặt của access_token và client_secret phải giống nhau.

Truy vấn điểm cuối GET oauth/revoke.

Yêu cầu mẫu

curl -i -X GET "https://graph.facebook.com/{graph-api-version}/oauth/revoke?   
    client_id={app-id}&
    client_secret={app-secret}&
    revoke_token={system-user-access-token-to-revoke}&
    access_token={your-access-token}"

Phản hồi mẫu

{
  "success":"true",
}

Xoay vòng mã truy cập

Xoay vòng mã là một biện pháp bảo mật có thể giúp giảm thiểu rủi ro, ví dụ: hạn chế thiệt hại do mã bị rò rỉ. Tương tự như việc thay đổi mật khẩu, bạn có thể hạn chế thiệt hại tiềm ẩn do rò rỉ hoặc thất lạc mã bằng cách thường xuyên thay đổi mã truy cập. Hiện tại, hệ thống của chúng tôi hỗ trợ xoay vòng người dùng hệ thống mà không cần dừng chạy. Để thực hiện việc này, hãy làm theo hướng dẫn sau:

Làm mới mã truy cập dành cho người dùng hệ thống qua API Làm mới SUAT. API Làm mới SUAT sẽ trả về mã truy cập mới dành cho người dùng hệ thống. Mã mới này có hiệu lực trong 60 ngày kể từ ngày làm mới. Mã cũ vẫn có thể hoạt động cho đến khi hết hạn (trong vòng 60 kể từ ngày tạo).
Triển khai Mã truy cập mới dành cho người dùng hệ thống.
Thu hồi Mã truy cập cũ dành cho người dùng hệ thống thông qua API Thu hồi SUAT. Mã sẽ bị vô hiệu hóa ngay lập tức và không thể sử dụng lại sau khi thu hồi.