README

Laravel Zoom API 客户端

Laravel Zoom API 包

支持我们

我们在创建开源包上投入了大量资金，如果您使用这些包的产品赚钱，我们将非常感激赞助。

我们的 API 使命！

让我们说实话，API 遍布各个角落，并且不一致。因此，我们致力于为所有需要 API 客户端并已开发 API 客户端库的 Laravel 用户改变这一点，我们的 API 是在它之上构建的，以提供一组一致的功能。

更新和问题

我们只通过 Github 接受问题。

我们会尽快更新安全性和错误修复，其他拉取请求和改进将在我们能够执行时进行。

您可以在 Twitter 上关注我们，我们将发布任何重大更新。 MacsiDigital Twitter

安装

您可以通过 composer 安装此包。

composer require macsidigital/laravel-zoom

关于版本：

1.0 - 已弃用 - 仅为客户项目快速构建，不建议使用此版本。
2.0 - Laravel 5.5 - 5.8 - 已弃用，不再维护
3.0 - Laravel 6.0 - 在维护中，欢迎创建拉取请求。这是一个开源项目，是双向的。
4.0 - Laravel 7.0 - 8.0 - 在维护中，欢迎创建拉取请求。这是一个开源项目，是双向的。

配置文件

发布配置文件

php artisan vendor:publish --provider="MacsiDigital\Zoom\Providers\ZoomServiceProvider"

这将在您的配置目录中创建一个 zoom.php 配置文件：

return [
    'apiKey' => env('ZOOM_CLIENT_KEY'),
    'apiSecret' => env('ZOOM_CLIENT_SECRET'),
    'baseUrl' => 'https://api.zoom.us/v2/',
    'token_life' => 60 * 60 * 24 * 7, // In seconds, default 1 week
    'authentication_method' => 'jwt', // Only jwt compatible at present
    'max_api_calls_per_request' => '5' // how many times can we hit the api to return results for an all() request
];

您需要将 ZOOM_CLIENT_KEY 和 ZOOM_CLIENT_SECRET 添加到您的 .env 文件中。

请注意 tokenLife，许多使用旧 API 的用户表示 token 过期得太快，所以我们默认设置了更长的 lifeTime，更重要的是，我们使其可定制。

这就足够了。

使用方法

一切都被设置为与 Laravel 语法相似。因此，使用它应该与 Eloquent 类似，甚至到关系层面。

不幸的是，Zoom API 并不太统一，有点混乱。但我们希望使其统一和逻辑。但是，您仍然需要阅读 Zoom 文档以了解哪些是可能的，哪些是不可能的。

目前我们覆盖以下模块：

用户
角色
会议
过去的会议
网络研讨会
过去的网络研讨会
录制

看起来不多，但会议和网络研讨会是两个主要模块，包括调查、注册问题、注册者、评论员和各种其他关系。

请注意，某些功能仅适用于某些计划类型。请检查 Zoom 文档。

连接

要获取访问点，您可以简单地创建一个新的实例和资源。

    $user = Zoom::user();

访问模型

处理模型有两大方式：直接从访问入口点通过外观调用它们，或者使用标准的php 'new' 方法并传递访问入口点。

    $user = Zoom::user();

    //or
    
    $zoom = new \MacsiDigital\Zoom\Support\Entry;
    $user = new \MacsiDigital\Zoom\User($zoom);

自定义设置

如果您想使用与您 zoom.php 配置文件中不同的配置值，可以将这些值作为参数传递给 \MacsiDigital\Zoom\Support\Entry，如下所示。

    $zoom = new \MacsiDigital\Zoom\Support\Entry($apiKey, $apiSecret, $tokenLife, $maxQueries, $baseUrl);

处理模型

正如所述，我们致力于实现与 Laravel 相似的功能，因此您可以在 Laravel 中做的几乎所有事情，这里都可以做，除了任何特定于数据库的功能，因为我们没有使用数据库。

    $user = Zoom::user()->create([...]);

    $user = Zoom::user()->find(...);

    $users = Zoom::user()->all();

    $meetings = Zoom::user()->find(...)->meetings;

    // Even this
    
    $user = Zoom::user()->find(...); 
    $meeting = Zoom::meeting()->make([...]);
    $user->meetings()->save($meeting);

每个模型也可能有一些自定义函数，Zoom 有一些独特功能。我们试图在下文中的资源部分列出所有这些。

    $user = Zoom::user()->create([...]);

    $user->updateProfilePicture($image); // Path to image

常见获取函数

第一个

我们使用第一个函数来返回记录集的第一条记录。这将返回一个实例化的模型。

    $user = Zoom::user()->where('status', 'active')->first();

查找

我们使用查找函数通过搜索唯一属性来返回记录。这将返回一个实例化的模型。

    $user = Zoom::user()->find('id');

    //or

    $user = Zoom::user()->find('email@address.com');

    // for most models this is only the id.  The past models utilise the uuid instead of the id.

全部

查找全部函数返回一个定制的 Laravel 集合，我们称之为结果集。

  $users = Zoom::user()->all();

调用全部函数时，我们将进行最多 5 次API调用以检索所有数据，即 5 x 300 条记录（最大允许值），即每次请求最多 1500 条记录。这可以在配置中通过更新 'max_api_calls_per_request' 来修改。

有关详细信息，请参阅以下结果集。

获取

当我们想检索过滤后的记录时，我们使用获取函数。请注意，Zoom 在过滤方面提供的选择不多。所以请查看文档。

    $users = Zoom::user()->where('status', 'active')->get();

    // We can also pass
    
    $users = Zoom::user()->where('status', '=', 'active')->get();

在调用获取调用时，我们将自动分页结果，默认为 30 条记录。您可以通过调用分页函数来增加/减少这个数字。

    $users = Zoom::user()->where('status', 'active')->paginate(100)->get(); // will return 100 records

您可以禁用分页，使其与 all() 函数表现相同

    $users = Zoom::user()->where('status', 'active')->setPaginate(false)->setPerPage(300)->get(); // will return 300 records * 5 request (or amount set in config) = 1500 records

resultSet

全部和获取函数返回一个 resultSet，这是一个增强的 Laravel 集合。像集合一样，我们可以调用 toArray 和 toJson 函数，将数据放置在 'data' 字段中，并添加一些关于总记录数和页面信息的元信息。

    // toArray()
    array:5 [
        "current_page" => 1
        "data" => array:5 [
            0 => array:11 [
              "uuid" => "...."
              "id" => ....
              "host_id" => "...."
              "topic" => "Team managers meeting"
              "type" => 2
              "start_time" => "2020-05-09T14:00:00+00:00"
              "duration" => 180
              "timezone" => "Europe/London"
              "created_at" => "2020-05-09T12:34:23+00:00"
              "join_url" => "https://zoom.us/j/...."
              "user_id" => "...."
            ]
            1 => array:11 [
              "uuid" => "...."
              "id" => ....
              "host_id" => "...."
              "topic" => "Onboarding meeting with Rosie Doe"
              "type" => 2
              "start_time" => "2020-05-10T13:30:00+00:00"
              "duration" => 180
              "timezone" => "Europe/London"
              "created_at" => "2020-05-10T13:19:41+00:00"
              "join_url" => "https://zoom.us/j/...."
              "user_id" => "...."
            ]
            2 => array:11 [
              "uuid" => "...."
              "id" => ....
              "host_id" => "...."
              "topic" => "Property tracking application meeting"
              "type" => 2
              "start_time" => "2020-05-14T15:30:00+00:00"
              "duration" => 60
              "timezone" => "Europe/London"
              "created_at" => "2020-05-14T08:45:32+00:00"
              "join_url" => "https://zoom.us/j/...."
              "user_id" => "...."
            ]
            3 => array:11 [
              "uuid" => "...."
              "id" => ....
              "host_id" => "...."
              "topic" => "Marketing meeting with John Doe"
              "type" => 2
              "start_time" => "2020-05-22T09:30:00+00:00"
              "duration" => 60
              "timezone" => "Europe/London"
              "created_at" => "2020-05-22T08:11:06+00:00"
              "join_url" => "https://zoom.us/j/...."
              "user_id" => "...."
            ]
            4 => array:11 [
              "uuid" => "...."
              "id" => ....
              "host_id" => "...."
              "topic" => "New Meeting Test"
              "type" => 2
              "start_time" => "2020-05-28T16:00:00+00:00"
              "duration" => 60
              "timezone" => "Europe/London"
              "created_at" => "2020-05-26T14:38:15+00:00"
              "join_url" => "https://zoom.us/j/...."
              "user_id" => "...."
            ]
        ]
        "last_page" => 1
        "per_page" => 1500
        "total" => 5
    ]

有一些额外的辅助函数。

如果我们的数据集大于返回的记录，我们将调用 nextPage() 函数来返回下一页的记录。

    $meetings->nextPage();

然后我们也可以通过调用 previousPage() 函数导航回前一页。在这种情况下，我们将返回缓存的结果而不是查询API。

    $meetings->previousPage();

还有一个函数可以积累更多记录，如果您调用 getNextRecords() 函数，它将检索下一 1500 条结果并将它们添加到当前记录中，因此您可以在需要时运行 3000 条记录。

    $meetings->getNextRecords();

不建议混合页面导航与积累记录函数。

还有一些辅助函数。

    $meetings->hasMorePages();
    $meetings->isFirstPage();
    $meetings->totalRecords();
    $meetings->currentPage();
    $meetings->lastPage();
    $meetings->nextPageNumber();
    $meetings->previousPageNumber();
    $meetings->firstPage(); // returns first page number which in this case will always be 1
    $meetings->perPage(); // returns how many results we return per page

如上所述，我们使用集合作为记录集的基础，因此集合中可能的一切在这里都是可能的。由于 Zoom 的过滤能力有限，我们可以使用集合的 'where' 函数，例如。

持久化模型

同样，目标是与 Laravel 相似，因此您可以利用 save、create、update 和 make 方法。

保存

为了保存模型，我们将使用 save 方法，这将确定模型是新的还是现有的，并根据需要插入或更新模型。

    $user = Zoom::user()->find('id');

    $user->first_name = 'changed';

    $user->save();

创建

目前，只有用户模型和角色模型可以直接创建，大多数其他模型需要作为关系的一部分创建，有关详细信息，请参阅下文。

要创建用户。

  Zoom::user()->create([
        'first_name' => 'First Name',
        'last_name' => 'Last Name',
        'email' => 'test@test.com',
        'password' => 'secret'
    ]); 
    // will return the created model so you can capture it if required.
    $user = Zoom::user()->create([
        'first_name' => 'First Name',
        'last_name' => 'Last Name',
        'email' => 'test@test.com',
        'password' => 'secret'
    ]);

Make

Make 与 create 类似，但它不会将模型持久化到 API 中。这对于关系模型很有用，下文将有更多介绍。

    $meeting = Zoom::meeting()->make([...]); 

    Zoom::user()->find('id')->meetings()->save($meeting);

更新

我们还可以批量更新属性。

    $user = Zoom::user()->find('id')->update(['field' => 'value', 'another_field' => 'value']);

关系

我们API客户端的新版本中的一项重大变化是我们使用了类似于Laravel的关系。要获取与用户关联的所有会议，我们会这样调用。

    $meetings = Zoom::user()->find(...)->meetings;

在Zoom API中，一些关系会直接与父模型返回，而一些则需要额外的API调用（了解这一点对于性能和API速率限制来说是有价值的）。

值得注意的是，我们是通过调用 ->meetings 来返回结果集。如果我们调用 ->meetings() 函数，我们将收到关系对象，可以进一步查询。

    $meetings = Zoom::user()->find(...)->settings(); // Returns HasOne relationship model

    $meetings = Zoom::user()->find(...)->meetings(); // Returns HasMany relationship model

这对于需要过滤结果时非常有用。

    $meetings = Zoom::user()->find(...)->meetings()->where('type', 'scheduled')->get();

如上所述，Zoom的查询过滤器非常有限，所以请查阅Zoom文档。

保存 & 创建

我们可以利用关系模型上的创建和保存函数来创建需要关系的模型。

    // Save Method

    $meeting = Zoom::meeting()->make([...]); 
    Zoom::user()->find('id')->meetings()->save($meeting); 

    // Create Method

    Zoom::user()->find('id')->meetings()->create([...]);

我们还可以利用Make和Attach方法来创建和附加模型到父模型而不持久化模型。这对于需要作为父模型一部分保存的子模型来说非常有用。

    // Create Method

    $meeting = Zoom::user()->find('id')->meetings()->make([...]); 

    $meeting->recurrence()->make([...]); // will attach to parent but not persist

    $meeting->save() // will save meeting and the attached recurrence model.

    // Attach Method

    $meeting = Zoom::meeting()->create([...]); 

    $recurrence = Zoom::meeting()->recurrence()->make([...]);
    $meeting->attach($recurrence);  // will attach to parent but not persist

    $meeting->save() // will save meeting and the attached recurrence model.

    // The later is very uncommon in Zoom and unlikely to be used due to the setup of relationships, but is an option.

验证

尽可能地将验证集成到API中，如果存在验证错误，则会抛出异常。如果我们的验证失败并且Zoom请求返回错误，那么我们将抛出HTTP异常。

如果API中的验证发生变化或者某些东西没有正常工作，那么最好的办法是修改失败模型的请求对象并提交一个pull请求。

资源

我们简要概述了常见的模型，我们没有包含任何验证要求，你需要查阅文档。

角色

    //To get a new instance
    
    Zoom::role();

    // available retrieve functions
     
    $role->find($id); // by id
    $role->all();
    $role->get();
    $role->first();

    // No available queries

    // Relationships
    $role->members // HasMany relationship, returns all users with role
    $role->privileges // hasOne relationship, list of all privileges

    // Special functions
     
    // Assign and remove role from users
    $role->giveRoleTo($user)
    $role->removeRoleFrom($user)

    // delete
    $role->delete(); // Delete (destroy) role.

用户

这是Zoom中大多数模型的主要访问方式。

    //To get a new instance
    
    Zoom::user();

    // available retrieve functions
     
    Zoom::user()->find('test@example.com'); // by id or email
    Zoom::user()->all();
    Zoom::user()->get();
    Zoom::user()->first();

    // Available queries
     
    Zoom::user()->where('type', 'active')->get(); // Allowed values active, inactive and pending
    Zoom::user()->where('role_id', *id*)->get(); // Allowed values are from the Roles model.

    // Relationships
    $user->setting // HasOne relationship
    $user->meetings // HasMany relationship
    $user->webinars // HasMany relationship
    $user->assistants // hasMany relationship
    $user->schedulers // hasMany relationship
    $user->permission // hasOne relationship
    $user->token // hasOne relationship
    $user->recordings // hasMany relationship

    // Special functions
     
    // To set license type
    $user->setBasic()
    $user->setLicensed()
    $user->setOnPrem()

    // Update functions
    $user->updateProfilePicture($image) // should pass the path to the image
    $user->updateStatus($status); // Allowed values active, deactivate
    $user->updatePassword($password); 
    $user->updateEmail($email);

    // disassociate & delete
    $user->disassociate(); // Disassociate from current account, user can still login to their own account.
    $user->delete(); // Delete (destroy) user.

用户设置

    //To get a new instance
    
    Zoom::setting();

    // can only be retrieved through a user
     
    $user->settings; 

    // To get sub relations then call the relationship of the setting
    
    $user->settings->scheduleMeeting;
    $user->settings->emailNotification;
    $user->settings->feature;
    $user->settings->inMeeting;
    $user->settings->integration;
    $user->settings->recording;
    $user->settings->telephony;
    $user->settings->tsp;

    // To update a setting
     
    $settings = $user->settings;
    $settings->scheduleMeeting->host_video = false;
    $settings->save();

    // Available queries
     
    $user()->settings()->where('login_type', '0')->get(); // Allowed values 0 => facebook, 1 => google, 99 => API, 100 => Zoom, 101 => SSO
    // Below not yet setup
    // $user()->settings()->where('option', 'meeting_authentication')->get(); // Allowed values meeting_authentication, recording_authentication.

会议

    //To get a new instance
    
    $meeting = Zoom::meeting();

    // To create we have to go through a user model
     
    $meeting = Zoom::user()->find(id)->meetings()->create([...]);

    $meeting = Zoom::meeting()->make([...]);
    $user = Zoom::user()->find(id)->meetings()->save($meeting);

    // To create a recurring meeting, this is just an example, you need to consult documentation to get the settings you require
    
    $meeting = Zoom::meeting()->make([
      'topic' => 'New meeting',
      'type' => 8,
      'start_time' => new Carbon('2020-08-12 10:00:00'), // best to use a Carbon instance here.
    ]);

    $meeting->recurrence()->make([
      'type' => 2,
      'repeat_interval' => 1,
      'weekly_days' => 2,
      'end_times' => 5
    ]);

    $meeting->settings()->make([
      'join_before_host' => true,
      'approval_type' => 1,
      'registration_type' => 2,
      'enforce_login' => false,
      'waiting_room' => false,
    ]);

    $user->meetings()->save($meeting);

    // To retrieve multiple records we need to go through the user model

    $user->meetings()->all();
    $user->meetings;  // same as above
    $user->meetings()->get();
    $user->meetings()->first();

    // available retrieve functions
     
    $meeting->find(id); // by id

    // We can update direct
    
    Zoom::meeting()->find(id)->update([...]);

    // or by using save function
    // 
    $meeting->save();

    // Available queries
     
    $user->meetings()->where('type', 'scheduled')->get(); // Allowed values scheduled, live and upcoming

    // Relationships
    $meeting->registrants // HasMany relationship
    $meeting->setting // HasOne relationship
    $meeting->invitation // HasOne relationship
    $meeting->occurrences // hasMany relationship
    $meeting->recurrence // hasOne relationship
    $meeting->polls // hasMany relationship
    $meeting->liveStream // hasOne relationship
    $meeting->registrationQuestions // hasMany relationship
    $meeting->trackingFields // hasMany relationship
    $meeting->recording // hasOne relationship

    // Once we have the meeting we can update registrants
     
    $registrant = Zoom::meeting()->registrants()->create([...]);

    // or
     
    $registrant = Zoom::meetingRegistrant()->make([...]);
    $meeting->registrants()->save($registrant);
    
    // To retrieve occurrences, Zoom requires both meeting and occurrence ID's, so we have to 
    // first retrieve the meeting
     
    $occurrence = Zoom::meeting()->find('...')->occurrences()->find('...');

    // You can then register people to that occurrence
     
    $registrant = Zoom::meetingRegistrant()->make([...]);
    
    $occurrence->registrants()->save($registrant);

    // Special functions
     
    // End Meeting
    $meeting->endMeeting();

    // delete
    $meeting->delete($scheduleForReminder); // Delete (destroy) meeting. ScheduleForReminder true by default

    //Delete Meeting Recording
    $meeting->recording->delete();  //Delete (destroy) the recording of the meeting.

网络研讨会

    //To get a new instance
    
    $webinar = Zoom::webinar();

    // To create we have to go through a user model
     
    $webinar = Zoom::user()->find(id)->webinars()->create([...]);

    $webinar = Zoom::webinar()->make([...]);
    $user = Zoom::user()->find(id)->webinars()->save($webinar);
    
    // To create a recurring meeting, this is just an example, you need to consult documentation to get the settings you require
    
    $webinar = Zoom::webinar()->make([
      'topic' => 'New webinar',
      'type' => 8,
      'start_time' => new Carbon('2020-08-12 10:00:00'), // best to use a Carbon instance here.
    ]);

    $webinar->recurrence()->make([
      'type' => 2,
      'repeat_interval' => 1,
      'weekly_days' => 2,
      'end_times' => 5
    ]);

    $webinar->settings()->make([
      'approval_type' => 1,
      'registration_type' => 2,
      'enforce_login' => false,
    ]);

    $user->webinars()->save($webinar);

    // To retrieve multiple records we need to go through the user model

    $user->webinars()->all();
    $user->webinars;  // same as above
    $user->webinars()->get();
    $user->webinars()->first();

    // available retrieve functions
     
    $webinar->find(id); // by id

    // We can update direct
    
    Zoom::webinar()->find(id)->update([...]);

    // or use the save function
    
    $webinar->save();

    // Relationships
    $webinar->registrants // HasMany relationship
    $webinar->panelists // HasMany relationship
    $webinar->setting // HasOne relationship
    $webinar->invitation // HasOne relationship
    $webinar->occurrences // hasMany relationship
    $webinar->recurrence // hasOne relationship
    $webinar->polls // hasMany relationship
    $webinar->registrationQuestions // hasMany relationship
    $webinar->trackingSources // hasMany relationship
    $webinar->trackingFields // hasMany relationship

    // To retrieve an occurrence, Zoom requires both webinar and occurnce ID's, so we have to 
    // first retrieve the webinar
     
    $occurrence = Zoom::webinar()->find('...')->occurrences()->find('...');

    // You can retrieve all occurrences
    
    $occurrence = Zoom::webinar()->find('...')->occurrences;

    // Once we have the webinar we can update registrants / panelists
     
    $registrant = Zoom::webinarRegistrant()->create([...]);

    $webinar->registrants()->save($registrant);

    $registrant = Zoom::panelist()->create([...]);

    $webinar->panelists()->save($panelist);

    // Special functions
     
    // End Webinar
    $webinar->endWebinar()

    // delete
    $webinar->delete(); // Delete (destroy) webinar.

会议/网络研讨会发生情况

我们正在显示会议信息，你需要将会议切换到网络研讨会以显示网络研讨会。

    // cant be instantiated or created directly, has to be created by setting up a recurrence
    // model on Meeting/Webinar Creation
    //
    // To retrieve occurrences we need to go through the meeting/webinar model, 
    // 
    // Only try to retrieve for a meeting/webinar that recurs, otherwise you will just get returned a
    // meeting/webinar model which will throw an error.

    $meeting->occurrences; // returns MeetingOccurrence model / WebinarOccurrences model

    // To get an occurrence

    $occurrence = $meeting->occurrences()->find(*id*); // Returns an Occurence model

    // Once we have the recurrence we can update registrants / panelists to that occurrence instance
     
    $registrant = Zoom::meetingRegistrant()->create([...]);

    $occurrence->registrants()->save($registrant);

    // Relationships
    $occurrence->registrants // HasMany relationship (meeting only)

    // An occurrence can also be updated directly
    $occurrence->save(); // update only, can't be created directly.
    
    // Single occurrences can also be deleted
    $occurrence->delete();

会议/网络研讨会设置

我们正在显示会议信息，你需要将会议切换到网络研讨会以显示网络研讨会。

    //To get a new instance
    
    $settings = Zoom::meetingSetting();

    // To create we have to go through a meeting model
     
    $setting = $meeting->settings()->create([...]);

    $settings = Zoom::meetingSetting()->make([...]);
    $meeting = $meeting->settings()->save($settings);

    // To retrieve settings we need to go through the meeting model

    $meeting->settings; // returns MeetingSetting model / WebinarSettings model

    // Relationships
    $setting->globalDialInNumbers // HasMany relationship (meeting only)
    $setting->globalDialInCountries // HasMany relationship

过去的会议

即将推出

过去的网络研讨会