Trang này được dịch bởi Cloud Translation API.

Bắt đầu

Tài liệu này cung cấp tất cả thông tin cơ bản mà bạn cần để bắt đầu sử dụng thư viện. Tài liệu này đề cập đến các khái niệm về thư viện, đưa ra ví dụ cho nhiều trường hợp sử dụng, và cung cấp đường liên kết đến nhiều thông tin khác.

Thiết lập

Bạn cần hoàn tất một số bước thiết lập trước khi có thể sử dụng thư viện này:

Nếu chưa có Tài khoản Google, đăng ký.
Nếu bạn chưa từng tạo dự án Google API Console, hãy đọc Trang Quản lý dự án và tạo một dự án trong Bảng điều khiển API của Google.
Cài đặt gói NuGet bạn muốn xử lý.

Xác thực và uỷ quyền

Điều quan trọng là bạn phải nắm được những kiến thức cơ bản về cách xử lý việc xác thực và uỷ quyền API. Tất cả lệnh gọi API phải sử dụng quyền truy cập đơn giản hoặc được uỷ quyền (được định nghĩa bên dưới). Nhiều phương thức API yêu cầu quyền truy cập được cấp phép, nhưng một số phương thức có thể sử dụng một trong hai phương thức đó. Một số phương thức API có thể hoạt động theo cách khác, tuỳ thuộc vào việc bạn sử dụng quyền truy cập đơn giản hay quyền truy cập được uỷ quyền. Hãy xem tài liệu về phương thức của API để xác định loại quyền truy cập phù hợp.

1. Quyền truy cập API đơn giản (khoá API)

Các lệnh gọi API này không truy cập vào bất kỳ dữ liệu riêng tư nào của người dùng. Ứng dụng của bạn phải tự xác thực là ứng dụng thuộc về đối với dự án Google API Console của bạn. Điều này là cần thiết để đo lường mức sử dụng dự án cho mục đích kế toán.

Khoá API: Để xác thực ứng dụng của bạn, hãy sử dụng Khoá API cho dự án Bảng điều khiển API của bạn. Mọi lệnh gọi truy cập đơn giản mà ứng dụng của bạn thực hiện đều phải bao gồm khoá này.

2. Quyền truy cập vào API (OAuth 2.0)

Các lệnh gọi API này truy cập vào dữ liệu riêng tư của người dùng. Trước khi bạn có thể gọi cho họ, người dùng có quyền truy cập vào dữ liệu cá nhân phải cấp cho ứng dụng của bạn quyền truy cập. Do đó, đơn đăng ký của bạn phải được xác thực, người dùng phải cấp quyền truy cập cho ứng dụng của bạn, và người dùng phải được xác thực để cấp quyền truy cập đó. Tất cả những điều này được thực hiện nhờ OAuth 2.0 và các thư viện được viết cho ứng dụng này.

Phạm vi: Mỗi API xác định một hoặc nhiều phạm vi khai báo một tập hợp thao tác được phép. Ví dụ: API có thể có phạm vi chỉ đọc và đọc-ghi. Khi ứng dụng của bạn yêu cầu quyền truy cập vào dữ liệu người dùng, yêu cầu phải bao gồm một hoặc nhiều phạm vi. Người dùng cần phê duyệt phạm vi truy cập mà ứng dụng của bạn đang yêu cầu.

Làm mới và truy cập vào mã thông báo: Khi người dùng cấp quyền truy cập vào ứng dụng của bạn, máy chủ uỷ quyền OAuth 2.0 cung cấp cho ứng dụng của bạn mã làm mới và mã truy cập. Những mã thông báo này chỉ hợp lệ trong phạm vi được yêu cầu. Ứng dụng của bạn dùng mã truy cập để cho phép lệnh gọi API. Mã truy cập sẽ hết hạn, nhưng mã làm mới thì không. Ứng dụng của bạn có thể dùng mã làm mới để lấy mã truy cập mới.

Mã ứng dụng khách và mật khẩu ứng dụng khách: Các chuỗi này nhận dạng duy nhất ứng dụng của bạn và dùng để lấy mã thông báo. Các API này được tạo cho dự án của bạn trên Bảng điều khiển API. Có 3 loại mã ứng dụng khách, nên hãy nhớ tìm đúng loại đơn đăng ký của bạn:

Mã ứng dụng khách ứng dụng web
Mã ứng dụng khách ứng dụng đã cài đặt
Mã khách hàng của tài khoản dịch vụ

Ví dụ

Trong phần này, có các ví dụ về việc sử dụng API đơn giản khi chưa được phép. Để biết thêm thông tin về lệnh gọi uỷ quyền, hãy xem Trang OAuth 2.0 cho .NET.

Ví dụ về API đơn giản

Ví dụ này sử dụng quyền truy cập API đơn giản cho một ứng dụng dòng lệnh. Phương thức gọi Google Discovery API để liệt kê tất cả API của Google.

Ví dụ về chế độ thiết lập

Lấy khoá API đơn giản. Để tìm khoá API cho ứng dụng của bạn, hãy làm như sau:

Mở trang Thông tin đăng nhập trong Bảng điều khiển API.
API này hỗ trợ hai loại thông tin xác thực. Tạo bất cứ thông tin đăng nhập nào phù hợp với dự án của bạn:
- OAuth 2.0: Bất cứ khi nào ứng dụng của bạn yêu cầu người dùng riêng tư thì ứng dụng phải gửi mã thông báo OAuth 2.0 cùng với yêu cầu. Thông tin trước tiên sẽ gửi ID ứng dụng khách và có thể là mật khẩu ứng dụng khách để lấy mã thông báo. Bạn có thể tạo thông tin đăng nhập OAuth 2.0 cho web ứng dụng, tài khoản dịch vụ hoặc ứng dụng đã cài đặt.
  
  Để biết thêm thông tin, hãy xem tài liệu về OAuth 2.0.
- Khoá API: Một yêu cầu không cung cấp mã thông báo OAuth 2.0 phải gửi API . Khoá này giúp xác định dự án của bạn và cấp quyền truy cập vào API, hạn mức và .
  
  API này hỗ trợ một số loại quy định hạn chế đối với khoá API. Nếu khoá API mà bạn chưa có, hãy tạo khoá API trong Console bằng cách nhấp vào Tạo thông tin xác thực > Khoá API. Bạn có thể hạn chế khoá này trước khi dùng trong phiên bản phát hành công khai bằng cách nhấp vào Hạn chế khoá rồi chọn một trong Quy định hạn chế.

Để bảo mật khoá API, hãy làm theo các phương pháp hay nhất về một cách an toàn bằng cách sử dụng khoá API.

Ví dụ về mã

using System;
using System.Threading.Tasks;

using Google.Apis.Discovery.v1;
using Google.Apis.Discovery.v1.Data;
using Google.Apis.Services;

namespace Discovery.ListAPIs
{
    /// <summary>
    /// This example uses the discovery API to list all APIs in the discovery repository.
    /// https://developers.google.com/discovery/v1/using.
    /// <summary>
    class Program
    {
        [STAThread]
        static void Main(string[] args)
        {
            Console.WriteLine("Discovery API Sample");
            Console.WriteLine("====================");
            try
            {
                new Program().Run().Wait();
            }
            catch (AggregateException ex)
            {
                foreach (var e in ex.InnerExceptions)
                {
                    Console.WriteLine("ERROR: " + e.Message);
                }
            }
            Console.WriteLine("Press any key to continue...");
            Console.ReadKey();
        }

        private async Task Run()
        {
            // Create the service.
            var service = new DiscoveryService(new BaseClientService.Initializer
                {
                    ApplicationName = "Discovery Sample",
                    ApiKey="[YOUR_API_KEY_HERE]",
                });

            // Run the request.
            Console.WriteLine("Executing a list request...");
            var result = await service.Apis.List().ExecuteAsync();

            // Display the results.
            if (result.Items != null)
            {
                foreach (DirectoryList.ItemsData api in result.Items)
                {
                    Console.WriteLine(api.Id + " - " + api.Title);
                }
            }
        }
    }
}

Mẹo sử dụng khoá API:

Để sử dụng một dịch vụ cụ thể, bạn phải thêm tệp tham chiếu đến dịch vụ đó. Ví dụ: nếu bạn muốn sử dụng API Tasks, bạn nên cài đặt gói NuGet Google.Apis.Tasks.v1.
Để tạo một thực thể của một dịch vụ, bạn chỉ cần gọi hàm khởi tạo của dịch vụ đó. Ví dụ: new TasksService(new BaseClientService.Initializer {...});".
Tất cả các phương thức của một dịch vụ đều nằm trên các tài nguyên riêng lẻ trên chính đối tượng dịch vụ đó. Dịch vụ Khám phá có một tài nguyên Apis chứa phương thức List. Khi bạn gọi service.Apis.List(..), một đối tượng yêu cầu nhắm mục tiêu đến phương thức này sẽ được trả về.
Để thực thi một yêu cầu, hãy gọi phương thức Execute() hoặc ExecuteAsyc() trên một yêu cầu.
Đặt khoá API bằng thuộc tính ApiKey trên thực thể BaseClientService.Initializer.

Tìm thông tin về các API

Chiến lược phát hành đĩa đơn Các API được hỗ trợ trang liệt kê tất cả API có thể truy cập được bằng thư viện này cũng như các liên kết đến tài liệu.

Bạn cũng có thể sử dụng Trình khám phá API để duyệt qua các API, liệt kê các phương thức có sẵn và thậm chí là thử các lệnh gọi API từ trình duyệt của bạn.