README-VI.md

Thư viện đóng gói Twitter API v2.0 nhẹ và đa nền tảng 🐦

---

---

| English | 日本語 | Français | Tiếng Việt | বাংলা | Español | Deutsch | Português | 简体中文 |

---

• 1. Hướng dẫn 🌎
  • 1.1. Bắt đầu ⚡
    • 1.1.1. Cài đặt thư viện
    • 1.1.2. Import
    • 1.1.3. Implementation
  • 1.2. Các Endpoint được hỗ trợ 👀
    • 1.2.1. Các Tweet Service
      • 1.2.1.1. Tweet
      • 1.2.1.2. Các lượt thích
      • 1.2.1.3. Các lượt Retweet
      • 1.2.1.4. Các Tweet trích dẫn
      • 1.2.1.5. Tìm kiếm các Tweet
      • 1.2.1.6. Tra cứu các Tweet
      • 1.2.1.7. Đếm các Tweet
      • 1.2.1.8. Các đánh dấu (Bookmarks)
      • 1.2.1.9. Các dòng thời gian (Timelines)
      • 1.2.1.10. Các phản hồi đã ẩn
      • 1.2.1.11. Volume Stream
      • 1.2.1.12. Stream đã được lọc
    • 1.2.2. Service về người dùng
      • 1.2.2.1. Các lượt theo dõi
      • 1.2.2.2. Tra cứ người dùng
      • 1.2.2.3. Tắt tiếng người dùng
      • 1.2.2.4. Chặn
    • 1.2.3. Service về các Space
      • 1.2.3.1. Tìm kiếm các Space
      • 1.2.3.2. Tra cứu các Space
    • 1.2.4. Service về danh sách
      • 1.2.4.1. Tra cứu các danh sách
      • 1.2.4.2. Các Ghim
      • 1.2.4.3. Tra cứu Tweet
      • 1.2.4.4. Quản lý danh sách
      • 1.2.4.5. Các lượt theo dõi
      • 1.2.4.6. Các thành viên
    • 1.2.5. Compliance Service
      • 1.2.5.1. Batch Compliance
  • 1.3. Các mẹo 🏄
    • 1.3.1. Tên các phương thức
    • 1.3.2. Tạo App-Only Bearer Token
    • 1.3.3. Tham số Null trong Request
    • 1.3.4. Mở rộng các trường của đối tượng với expansions
    • 1.3.5. Mở rộng các trường của đối tượng với fields
  • 1.4. Sự đóng góp 🏆
  • 1.5. Những người đóng góp ✨
  • 1.6. Ủng hộ ❤️
  • 1.7. Giấy phép 🔑
  • 1.8. Thông tin thêm 🧐

1. Hướng dẫn 🌎

Thư viện này cung cấp cách dễ nhất để dùng Twitter API v2.0 trong Dart và các ứng dụng Flutter.

Hãy thả ❤️ và star cho repo này dể ủng hộ dự án!.

1.1. Bắt đầu ⚡

1.1.1. Cài đặt thư viện

Với Dart:

 dart pub add twitter_api_v2

Hoặc với Flutter:

 flutter pub add twitter_api_v2

1.1.2. Import

import 'package:twitter_api_v2/twitter_api_v2';

1.1.3. Implementation

Future<void> main() async {
  //! Bạn cần có các key và token ở trang https://developer.twitter.com
  final twitter = v2.TwitterApi(
    //! Xác thực (Authentication) với OAuth2.0 là mặc định.
    //!
    //! Lưu ý rằng để sử dụng các endpoint này cần các quyền cụ thể của người dùng,
    //! như các lượt tweet và lượt thích, bạn cần có một token được tạo ra bởi OAuth2.0 PKCE.

    bearerToken: 'YOUR_TOKEN_HERE',

    //! Hoặc có thể bạn sẽ thích sử dụng phương thức OAuth1.0a
    //! hơn phương thức OAuth2.0 PKCE. Thì bạn có thể sử dụng code sau đây
    //! để thiết lập OAuth1.0a token.
    //!
    //! Tuy nhiên, lưu ý rằng một vài endpoint không thể sử dụng phương thức OAuth 1.0a
    //! để xác thực.


    oauthTokens: v2.OAuthTokens(
      consumerKey: 'YOUR_CONSUMER_KEY_HERE',
      consumerSecret: 'YOUR_CONSUMER_SECRET_HERE',
      accessToken: 'YOUR_ACCESS_TOKEN_HERE',
      accessTokenSecret: 'YOUR_ACCESS_TOKEN_SECRET_HERE',
    ),
  );

  try {
    // Lấy về hồ sơ (profile) của người dùng đã xác thực
    final me = await twitter.users.lookupMe();
    // Lấy về các tweet với truy vấn tìm kiếm (query) tương ứng.
    final tweets = await twitter.tweets.searchRecent(
      query: '#ElonMusk',
      maxResults: 20,
      // Bạn có thể mở rộng kết quả tìm kiếm.
      expansions: [
        v2.TweetExpansion.authorId,
        v2.TweetExpansion.inReplyToUserId,
      ],
      tweetFields: [
        v2.TweetField.conversationId,
        v2.TweetField.publicMetrics,
      ],
      userFields: [
        v2.UserField.location,
        v2.UserField.verified,
        v2.UserField.entities,
        v2.UserField.publicMetrics,
      ],
    );

    await twitter.tweets.createLike(
      userId: me.data.id,
      tweetId: tweets.data.first.id,
    );

    // Stream endpoint với High-performance Volume thì có sẵn.
    final sampleStream = await twitter.tweets.connectSampleStream();
    await for (final response in sampleStream.stream.handleError(print)) {
      print(response);
    }

    // Stream endpoint với hiệu suất lọc cao cũng có sẵn.
    await twitter.tweets.createFilteringRules(
      rules: [
        v2.FilteringRuleParam(value: '#ElonMusk'),
        v2.FilteringRuleParam(value: '#Tesla'),
        v2.FilteringRuleParam(value: '#SpaceX'),
      ],
    );

    final filteredStream = await twitter.tweets.connectFilteredStream();
    await for (final response in filteredStream.stream.handleError(print)) {
      print(response.data);
      print(response.matchingRules);
    }
  } on TimeoutException catch (e) {
    print(e);
  } on v2.RateLimitExceededException catch (e) {
    print(e);
  } on v2.TwitterException catch (e) {
    print(e.response.headers);
    print(e.body);
    print(e);
  }
}

1.2. Các Endpoint được hỗ trợ 👀

1.2.1. Các Tweet Service

1.2.1.1. Tweet

Endpoint	Tên Phương Thức
POST /2/tweets	createTweet
DELETE /2/tweets/:id	destroyTweet

1.2.1.2. Các lượt thích

Endpoint	Tên Phương Thức
POST /2/users/:id/likes	createLike
DELETE /2/users/:id/likes/:tweet_id	destroyLike
GET /2/tweets/:id/liking_users	lookupLikingUsers
GET /2/users/:id/liked_tweets	lookupLikedTweets

1.2.1.3. Các lượt Retweet

Endpoint	Tên Phương Thức
POST /2/users/:id/retweets	createRetweet
DELETE /2/users/:id/retweets/:source_tweet_id	destroyRetweet
GET /2/tweets/:id/retweeted_by	lookupRetweetedUsers

1.2.1.4. Các Tweet trích dẫn

Endpoint	Tên Phương Thức
GET /2/tweets/:id/quote_tweets	lookupQuoteTweets

1.2.1.5. Tìm kiếm các Tweet

Endpoint	Tên Phương Thức
GET /2/tweets/search/all	searchAll
GET /2/tweets/search/recent	searchRecent

1.2.1.6. Tra cứu các Tweet

Endpoint	Tên Phương Thức
GET /2/tweets	lookupByIds
GET /2/tweets/:id	lookupById

1.2.1.7. Đếm các Tweet

Endpoint	Tên Phương Thức
GET /2/tweets/counts/all	countAll
GET /2/tweets/counts/recent	countRecent

1.2.1.8. Các đánh dấu (Bookmarks)

Endpoint	Tên Phương Thức
POST /2/users/:id/bookmarks	createBookmark
DELETE /2/users/:id/bookmarks/:tweet_id	destroyBookmark
GET /2/users/:id/bookmarks	lookupBookmarks

1.2.1.9. Các dòng thời gian (Timelines)

Endpoint	Tên Phương Thức
GET /2/users/:id/mentions	lookupMentions
GET /2/users/:id/tweets	lookupTweets
GET /2/users/:id/timelines/reverse_chronological	lookupHomeTimeline

1.2.1.10. Các phản hồi đã ẩn

Endpoint	Tên Phương Thức
PUT /2/tweets/:id/hidden	createHiddenReply
PUT /2/tweets/:id/hidden	destroyHiddenReply

1.2.1.11. Volume Stream

Endpoint	Tên Phương Thức
GET /2/tweets/sample/stream	connectSampleStream

1.2.1.12. Stream đã được lọc

Endpoint	Tên Phương Thức
POST /2/tweets/search/stream/rules	createFilteringRules
GET /2/tweets/search/stream/rules	lookupFilteringRules
GET /2/tweets/search/stream	connectFilteredStream

1.2.2. Service về người dùng

1.2.2.1. Các lượt theo dõi

Endpoint	Tên Phương Thức
POST /2/users/:id/following	createFollow
DELETE /2/users/:source_user_id/following/:target_user_id	destroyFollow
GET /2/users/:id/followers	lookupFollowers
GET /2/users/:id/following	lookupFollowings

1.2.2.2. Tra cứ người dùng

Endpoint	Tên Phương Thức
GET /2/users	lookupByIds
GET /2/users/:id	lookupById
GET /2/users/by	lookupByNames
GET /2/users/by/username/:username	lookupByName
GET /2/users/me	lookupMe

1.2.2.3. Tắt tiếng người dùng

Endpoint	Tên Phương Thức
POST /2/users/:id/muting	createMute
DELETE /2/users/:source_user_id/muting/:target_user_id	destroyMute
GET /2/users/:id/muting	lookupMutingUsers

1.2.2.4. Chặn

Endpoint	Tên Phương Thức
POST /2/users/:id/blocking	createBlock
DELETE /2/users/:source_user_id/blocking/:target_user_id	destroyBlock
GET /2/users/:id/blocking	lookupBlockingUsers

1.2.3. Service về các Space

1.2.3.1. Tìm kiếm các Space

Endpoint	Tên Phương Thức
GET /2/spaces/search	search

1.2.3.2. Tra cứu các Space

Endpoint	Tên Phương Thức
GET /2/spaces	lookupByIds
GET /2/spaces/:id	lookupById
GET /2/spaces/:id/buyers	lookupBuyers
GET /2/spaces/:id/tweets	lookupTweets
GET /2/spaces/by/creator_ids	lookupByCreatorIds

1.2.4. Service về danh sách

1.2.4.1. Tra cứu các danh sách

Endpoint	Tên Phương Thức
GET /2/lists/:id	lookupById
GET /2/users/:id/owned_lists	lookupOwnedBy

1.2.4.2. Các Ghim

Endpoint	Tên Phương Thức
POST /2/users/:id/pinned_lists	createPinnedList
DELETE /2/users/:id/pinned_lists/:list_id	destroyPinnedList
GET /2/users/:id/pinned_lists	lookupPinnedLists

1.2.4.3. Tra cứu Tweet

Endpoint	Tên Phương Thức
GET /2/lists/:id/tweets	lookupTweets

1.2.4.4. Quản lý danh sách

Endpoint	Tên Phương Thức
POST /2/lists	createPublicList
POST /2/lists	createPrivateList
DELETE /2/lists/:id	destroyList
PUT /2/lists/:id	updateListAsPublic
PUT /2/lists/:id	updateListAsPrivate

1.2.4.5. Các lượt theo dõi

Endpoint	Tên Phương Thức
POST /2/users/:id/followed_lists	createFollow
DELETE /2/users/:id/followed_lists/:list_id	destroyFollow
GET /2/lists/:id/followers	lookupFollowers
GET /2/users/:id/followed_lists	lookupFollowedLists

1.2.4.6. Các thành viên

Endpoint	Tên Phương Thức
POST /2/lists/:id/members	createMember
DELETE /2/lists/:id/members/:user_id	destroyMember
GET /2/lists/:id/members	lookupMembers
GET /2/users/:id/list_memberships	lookupMemberships

1.2.5. Compliance Service

1.2.5.1. Batch Compliance

Endpoint	Tên Phương Thức
POST /2/compliance/jobs	createJob
GET /2/compliance/jobs	lookupJobs
GET /2/compliance/jobs/:id	lookupJob

1.3. Các mẹo 🏄

1.3.1. Tên các phương thức

twitter_api_v2 sử dụng các tiền tố chuẩn sau tùy thuộc vào các đặc điểm của endpoint. Vì vậy, rất dễ dàng để tìm thấy phương thức tương ứng với endpoint mà bạn muốn sử dụng!

Tiền tố	Mô tả
lookup	Tiền tố này được gắn với các endpoint mà tham chiếu đến các tweet, người dùng, v.v.
search	Tiền tố này được gắn với các endpoint thực hiện các tìm kiếm mở rộng.
connect	Tiền tố này được gắn với các endpoint với high-performance streaming.
count	Tiền tố này được gắn với các endpoint đếm một đối tượng cụ thể.
create	Tiền tố này được gắn với các endpoint thực hiện trạng thái tạo chẳng hạn như Tweet và Theo dõi.
destroy	Tiền tố này được gắn với các endpoint thực hiện trạng thái hủy chẳng hạn như Tweet và Theo dõi.
update	Tiền tố này được gắn với các endpoint thực hiện trạng thái cập nhật.

1.3.2. Tạo App-Only Bearer Token

twitter_api_v2 cung cấp tiện ích để tạo / tìm mã app-only bearer token của bạn.

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

Future<void> main() async {
  final bearerToken = await v2.OAuthUtils.generateAppOnlyBearerToken(
    consumerKey: 'YOUR_CONSUMER_KEY',
    consumerSecret: 'YOUR_CONSUMER_SECRET',
  );

  print(bearerToken);
}

1.3.3. Tham số Null trong Request

Trong thư viện này, các tham số là không bắt buộc lúc gửi request, tức là các tham số tùy chọn, được định nghĩa là có thể null. Tuy nhiên, các nhà phát triển không cần phải biết về tham số null khi gửi yêu cầu khi sử dụng thư viện này.

Nó có nghĩa là các tham số được gán giá trị null sẽ được loại bỏ và bỏ qua một cách an toàn trước khi request được gửi đi.

Ví dụ, các tham số được gán bằng null sẽ bị bỏ qua trong request sau.

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

Future<void> main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  await twitter.tweets.createTweet(
    text: 'Hello, World!',
    // Các tham số này bị bỏ qua khi request vì chúng null.
    mediaIds: null,
    expansions: null,
  );
}

1.3.4. Mở rộng các trường của đối tượng với expansions

Ví dụ: có thể xảy ra trường hợp dữ liệu chỉ chứa một ID và bạn cũng muốn truy xuất đối tượng dữ liệu được liên kết với ID đó. Trong những trường hợp như vậy, thông số kỹ thuật Twitter API v2.0 được gọi là expansions rất hữu ích và thư viện này hỗ trợ thông số kỹ thuật đó.

Về cơ bản, nó có thể được sử dụng trong các endpoint để mà thực hiện giao tiếp GET như xử lý tra cứu và tìm kiếm. Một số trường cũng có thể được đưa vào thuộc tính include của TwitterResponse.

Bạn có thể sử dụng expansions như bên dưới:

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

Future<void> main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  try {
    final tweets = await twitter.tweets.searchRecent(
      query: '#ElonMusk',
      // Chỉ định các trường bạn cần!
      expansions: [
        v2.TweetExpansion.authorId,
        v2.TweetExpansion.inReplyToUserId,
      ],
    );

    print(tweets);
  } on v2.TwitterException catch (e) {
    print(e);
  }
}

Bạn có thể xem thêm chi tiết về expansions từ Tài liệu chính thức.

1.3.5. Mở rộng các trường của đối tượng với fields

Twitter API v2.0 hỗ trợ một thông số kỹ thuật rất thú vị, cho phép người dùng kiểm soát lượng dữ liệu có trong response object cho endpoint tùy thuộc vào tình huống. Nó được gọi là fields và thư viện này hỗ trợ đặc tả này.

Về cơ bản, nó có thể được sử dụng trong các endpoint thực hiện giao tiếp GET chẳng hạn như xử lý tra cứu và tìm kiếm. Một số trường cũng có thể được đưa vào trường include của TwitterResponse.

Bạn có thể sử dụng fields như bên dưới:

import 'package:twitter_api_v2/twitter_api_v2.dart' as v2;

Future<void> main() async {
  final twitter = v2.TwitterApi(bearerToken: 'YOUR_TOKEN_HERE');

  try {
    final tweets = await twitter.tweets.searchRecent(
      query: '#ElonMusk',
      maxResults: 20,
      expansions: v2.TweetExpansion.values,
      tweetFields: [
        v2.TweetField.conversationId,
        v2.TweetField.publicMetrics,
      ],
      userFields: [
        v2.UserField.location,
        v2.UserField.publicMetrics,
      ],
    );

    print(tweets);
  } on v2.TwitterException catch (e) {
    print(e);
  }
}

Lưu ý
Một số trường phải được kết hợp với expansions.

Bạn có thể xem thêm chi tiết về fields từ Tài liệu chính thức.

1.4. Sự đóng góp 🏆

Nếu bạn muốn đóng góp cho twitter_api_v2, vui lòng tạo issue hoặc tạo một Pull Request.

Có nhiều cách để đóng góp cho OSS. Ví dụ, các đề mục sau có thể được xem xét:

• Có các tham số request hoặc trường response không được thực hiện.
• Tài liệu lỗi thời hoặc không đầy đủ.
• Có cách hoặc ý tưởng tốt hơn để đạt được chức năng.
• vân vân...

Bạn có thể xem thêm chi tiết từ các nguồn bên dưới:

• Quy tắc ứng xử của những người đóng góp
• Các nguyên tắc đóng góp
• Style Guide (Hướng dẫn phong cách)

Hoặc bạn có thể tạo thảo luận nếu cần.

Hãy tham gia vào sự phát triển này, các ý kiến đa dạng giúp phần mềm tốt hơn!

1.5. Những người đóng góp ✨

Cảm ơn những người tuyệt vời này (emoji key):

Kato Shinya / 加藤 真也 💻 🖋 🔣 📖 🎨 💡 🔍 🤔 🚇 🚧 🧑‍🏫 📆 💬 👀 🛡️ 🌍 ⚠️ ✅	Andy Piper 🖋 📢	Konstantin 💻 🎨 📖 💡 ⚠️	Roberto Doering 💻 🎨 📖 💡 ⚠️ 🤔	Nitesh Sharma 💻 🎨 📖 💡 ⚠️ 🤔
ngoluuduythai 📖 🌍	Abdullah Al Mahmud 📖 🌍	Oumar fall 📖 🌍	Natalie Stroud 📖 🌍	novas1r1 📖 🌍 🤔
Ikko Ashimine 📖	Marcos Vinícius 📖 🌍	Mark O'Sullivan 🤔	bors-ng 🚧 👀	All Contributors 📖
Codecov ⚠️ 🚧 🛡️	FOSSA 🚧 🛡️	yuto90 📝 🖋 💡 ✅	normidar 🤔 💻 📖 💬	Tim Surkis 🐛 🤔 💬 📓
shinobi-art 🐛 💬	Tushar Mishra 💻	Azka Full Snack Developer:) 💬 🤔

Dự án này tuân theo đặc điểm kỹ thuật của all-contributors. Những đóng góp của bất kỳ hình thức nào đều được chào đón!

1.6. Ủng hộ ❤️

Cách đơn giản nhất để cho chúng tôi thấy sự ủng hộ của bạn là cho dự án một ngôi sao tại GitHub và Pub.dev.

Bạn cũng có thể hỗ trợ dự án này bằng cách trở thành nhà tài trợ trên GitHub:

Bạn cũng có thể hiển thị trên repository của mình rằng ứng dụng của bạn được tạo bằng twitter_api_v2 bằng cách sử dụng một trong các huy hiệu sau:

[![Powered by twitter_api_v2](https://img.shields.io/badge/Powered%20by-twitter_api_v2-00acee.svg)](https://github.com/twitter-dart/twitter-api-v2)
[![Powered by twitter_api_v2](https://img.shields.io/badge/Powered%20by-twitter_api_v2-00acee.svg?style=flat-square)](https://github.com/twitter-dart/twitter-api-v2)
[![Powered by twitter_api_v2](https://img.shields.io/badge/Powered%20by-twitter_api_v2-00acee.svg?style=for-the-badge)](https://github.com/twitter-dart/twitter-api-v2)

1.7. Giấy phép 🔑

Tất cả tài nguyên của twitter_api_v2 được cung cấp theo giấy phép BSD-3.

Lưu ý
Thông báo giấy phép trong source được xác thực nghiêm ngặt dựa trên .github / header-checker-lint.yml. Vui lòng kiểm tra header-checker-lint.yml để biết các tiêu chuẩn được phép.

1.8. Thông tin thêm 🧐

twitter_api_v2 được thiết kế và triển khai bởi Kato Shinya (@myConsciousness).

• Hồ sơ người sáng tạo
• Giấy phép
• Tài liệu API
• Ghi chú phát hành
• Báo cáo lỗi