README

Laravel Zoom API 客户端

Laravel Zoom API 包

支持我们

我们在创建开源包上投入了很多，如果您从使用这些包的产品中获得收入，我们将不胜感激赞助。

我们的API使命！

让我们坦白，API到处都是，而且不一致。因此，我们着手尝试改变所有需要API客户端的Laravel用户的这一现状，并开发了一个API客户端库，我们的API都是基于它构建的，以提供一组一致的功能。

更新与问题

我们只通过Github接受问题。

我们会尽快更新安全性和错误修复，其他pull请求和改进将根据我们的能力进行。

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

安装

您可以通过composer安装此包

composer require macsidigital/laravel-zoom

版本：

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

配置文件

发布配置文件

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

这将在您的config目录中创建一个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过期太快，所以我们默认设置了更长的生命周期，更重要的是，我们还使其可定制。

这就足够了。

使用方法

所有设置都是为了与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 Collection，我们称之为结果集。

  $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 Collection。像集合一样，我们可以调用 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 与 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

过去的会议

即将推出

过去的网络研讨会