Win/mac両対応のVBA用ライブラリ[VBA-Web]を使ってみよう

VBAでWebアクセスする方法を調べると、そのほとんどがWindowsAPIの「URLDownloadToFileを使って簡単にできる！」といった記事だ。まぁ間違ってはいないのだが、WindowsAPIを使うのでWindowsでのみ使える方法だ(当たり前)。mac「のみ」を使用している個人事業主も増えている昨今、mac版VBAにも対応したWebアクセスの方法を紹介している記事はいないのかと探していたところ、Win/mac両対応ライブラリ「[VBA-Web](https://github.com/VBA-tools/VBA-Web)」を発見した。ただ、日本語の情報がほとんど見つからなかったので、自分の備忘も兼ねてここで紹介したいと思う。

以下は公式「Readme」のGoogle翻訳。

---
VBA-Web
=======

VBA-Web (formerly Excel-REST) makes working with complex webservices and APIs easy with VBA on Windows and Mac. It includes support for authentication, automatically converting and parsing JSON, working with cookies and headers, and much more.

VBA-Web（以前のExcel-REST）は、WindowsとMacのVBAで複雑なWebサービスとAPIを簡単に操作できるようにします。 認証のサポート、JSONの自動変換と解析、Cookieとヘッダーの操作などが含まれます。
<a href="https://www.patreon.com/timhall">
  <img src="https://timhall.github.io/assets/donate-patreon@2x.png" width="217" alt="Donate">
</a>
Getting started
---------------

- Download the [latest release (v4.1.6)](https://github.com/VBA-tools/VBA-Web/releases)
- To install/upgrade in an existing file, use `VBA-Web - Installer.xlsm`
- To start from scratch in Excel, `VBA-Web - Blank.xlsm` has everything setup and ready to go

For more details see the [Wiki](https://github.com/VBA-tools/VBA-Web/wiki)

* [最新リリース（v4.1.6）](https://github.com/VBA-tools/VBA-Web/releases)をダウンロードします
* 既存のファイルにインストール/アップグレードするには、 `VBA-Web-Installer.xlsm`を使用します
* Excelでゼロから始めるために、 `VBA-Web-Blank.xlsm`はすべてのセットアップと準備が整っています

詳細については、[Wiki](https://github.com/VBA-tools/VBA-Web/wiki)

Upgrading
---------

To upgrade from Excel-REST to VBA-Web, follow the [Upgrading Guide](https://github.com/VBA-tools/VBA-Web/wiki/Upgrading-from-v3-to-v4)

Note: XML support has been temporarily removed from VBA-Web while parser issues for Mac are resolved.
XML support is still possible on Windows, follow [these instructions](https://github.com/VBA-tools/VBA-Web/wiki/XML-Support-in-4.0) to use a custom formatter.

Excel-RESTからVBA-Webにアップグレードするには、[アップグレードガイド](https://github.com/VBA-tools/VBA-Web/wiki/Upgrading-from-v3-to-v4)に従ってください

注：Macのパーサーの問題が解決されている間、XMLサポートはVBA-Webから一時的に削除されました。
WindowsでもXMLサポートは可能です。[これらの手順](https://github.com/VBA-tools/VBA-Web/wiki/XML-Support-in-4.0)に従ってカスタムフォーマッタを使用してください。

Notes
---

- Authentication support is built-in, with suppory for HTTP Basic, OAuth 1.0, OAuth 2.0, Windows, Digest, Google, and more. See [Authentication](https://github.com/VBA-tools/VBA-Web/wiki/Authentication) for more information
- For proxy environments, `Client.EnabledAutoProxy = True` will automatically load proxy settings
- Support for custom request and response formats. See [RegisterConverter](http://vba-tools.github.io/VBA-Web/docs/#/WebHelpers/RegisterConverter)

* 認証サポートが組み込まれており、HTTP Basic、OAuth 1.0、OAuth 2.0、Windows、Digest、Googleなどに対応しています。 詳細については、[認証](https://github.com/VBA-tools/VBA-Web/wiki/Authentication)を参照してください
* プロキシ環境の場合、 `Client.EnabledAutoProxy = True`は自動的にプロキシ設定を読み込みます
* カスタム要求および応答フォーマットのサポート。 [RegisterConverter](http://vba-tools.github.io/VBA-Web/docs/#/WebHelpers/RegisterConverter)を参照してください

Examples
-------

The following examples demonstrate using the Google Maps API to get directions between two locations.

次の例は、Google Maps APIを使用して2つの場所間のルートを取得する方法を示しています。

### GetJSON Example

```VBA
Function GetDirections(Origin As String, Destination As String) As String
    ' Create a WebClient for executing requests
    ' and set a base url that all requests will be appended to
    ' リクエストを実行するためのWebClientを作成し、
    ' すべてのリクエストが追加されるベースURLを設定します
    Dim MapsClient As New WebClient
    MapsClient.BaseUrl = "https://maps.googleapis.com/maps/api/"

    ' Use GetJSON helper to execute simple request and work with response
    ' GetJSONヘルパーを使用して単純な要求を実行し、応答を処理する
    Dim Resource As String
    Dim Response As WebResponse

    Resource = "directions/json?" & _
        "origin=" & Origin & _
        "&destination=" & Destination & _
        "&sensor=false"
    Set Response = MapsClient.GetJSON(Resource)

    ' => GET https://maps.../api/directions/json?origin=...&destination=...&sensor=false

    ProcessDirections Response
End Function

Public Sub ProcessDirections(Response As WebResponse)
    If Response.StatusCode = WebStatusCode.Ok Then
        Dim Route As Dictionary
        Set Route = Response.Data("routes")(1)("legs")(1)

        Debug.Print "It will take " & Route("duration")("text") & _
            " to travel " & Route("distance")("text") & _
            " from " & Route("start_address") & _
            " to " & Route("end_address")
    Else
        Debug.Print "Error: " & Response.Content
    End If
End Sub
```

There are 3 primary components in VBA-Web:

1. `WebRequest` for defining complex requests
2. `WebClient` for executing requests
3. `WebResponse` for dealing with responses.

In the above example, the request is fairly simple, so we can skip creating a `WebRequest` and instead use the `Client.GetJSON` helper to GET json from a specific url. In processing the response, we can look at the `StatusCode` to make sure the request succeeded and then use the parsed json in the `Data` parameter to extract complex information from the response.

VBA-Webには3つの主要コンポーネントがあります。

1. 複雑なリクエストを定義するための `WebRequest`
2. リクエストを実行するための `WebClient`
3. 応答を処理するための「WebResponse」。

上記の例では、リクエストはかなり単純なので、 `WebRequest`の作成をスキップして、代わりに` Client.GetJSON`ヘルパーを使用して特定のURLからjsonを取得できます。 レスポンスの処理では、 `StatusCode`を見てリクエストが成功したことを確認し、解析されたjsonを` Data`パラメーターで使用してレスポンスから複雑な情報を抽出します。

### WebRequest Example

If you wish to have more control over the request, the following example uses `WebRequest` to define a complex request.

リクエストをより詳細に制御したい場合は、次の例で `WebRequest`を使用して複雑なリクエストを定義します。

```VBA
Function GetDirections(Origin As String, Destination As String) As String
    Dim MapsClient As New WebClient
    MapsClient.BaseUrl = "https://maps.googleapis.com/maps/api/"

    ' Create a WebRequest for getting directions
    ' ルートを取得するためのWebRequestを作成する
    Dim DirectionsRequest As New WebRequest
    DirectionsRequest.Resource = "directions/{format}"
    DirectionsRequest.Method = WebMethod.HttpGet

    ' Set the request format
    ' -> Sets content-type and accept headers and parses the response
    ' リクエストフォーマットを設定する
    ' -> content-typeを設定し、ヘッダーを受け入れ、応答を解析します
    DirectionsRequest.Format = WebFormat.Json

    ' Replace {format} segment
    ' {format}セグメントを置き換える
    DirectionsRequest.AddUrlSegment "format", "json"

    ' Add querystring to the request
    ' クエリ文字列をリクエストに追加する
    DirectionsRequest.AddQuerystringParam "origin", Origin
    DirectionsRequest.AddQuerystringParam "destination", Destination
    DirectionsRequest.AddQuerystringParam "sensor", "false"

    ' => GET https://maps.../api/directions/json?origin=...&destination=...&sensor=false

    ' Execute the request and work with the response
    ' リクエストを実行してレスポンスを操作する
    Dim Response As WebResponse
    Set Response = MapsClient.Execute(DirectionsRequest)

    ProcessDirections Response
End Function

Public Sub ProcessDirections(Response As WebResponse)
    ' ... Same as previous example
End Sub
```

The above example demonstrates some of the powerful feature available with `WebRequest`. Some of the features include:

- Url segments (Replace {segment} in resource with value)
- Method (GET, POST, PUT, PATCH, DELETE)
- Format (json, xml, url-encoded, plain-text) for content-type and accept headers and converting/parsing request and response
- QuerystringParams
- Body
- Cookies
- Headers

For more details, see the `WebRequest` portion of the [Docs](https://vba-tools.github.io/VBA-Web/docs/)

上記の例は、 `WebRequest`で利用できる強力な機能の一部を示しています。 機能の一部は次のとおりです。

* URLセグメント（リソースの{segment}を値で置き換えます）
* メソッド（GET、POST、PUT、PATCH、DELETE）
* content-typeのフォーマット（json、xml、url-encoded、plain-text）、ヘッダーの受け入れ、リクエストとレスポンスの変換/解析
* QuerystringParams
* Body
* クッキー
* ヘッダー

詳細については、[Docs](https://vba-tools.github.io/VBA-Web/docs/)

### Authentication Example

The following example demonstrates using an authenticator with VBA-Web to query Twitter. The `TwitterAuthenticator` (found in the `authenticators/` [folder](https://github.com/VBA-tools/VBA-Web/tree/master/authenticators)) uses Twitter's OAuth 1.0a authentication and details of how it was created can be found in the [Wiki](https://github.com/VBA-tools/VBA-Web/wiki/Implementing-your-own-IAuthenticator).

次の例は、VBA-Webでオーセンティケーターを使用してTwitterにクエリを実行する方法を示しています。 `TwitterAuthenticator`（` authenticators / `[folder](https://github.com/VBA-tools/VBA-Web/tree/master/authenticators)にあります）はTwitterのOAuth 1.0a認証とその詳細を使用しています [Wiki](https://github.com/VBA-tools/VBA-Web/wiki/Implementing-your-own-IAuthenticator)にあります。

```VBA
Function QueryTwitter(Query As String) As WebResponse
    Dim TwitterClient As New WebClient
    TwitterClient.BaseUrl = "https://api.twitter.com/1.1/"

    ' Setup authenticator
    Dim TwitterAuth As New TwitterAuthenticator
    TwitterAuth.Setup _
        ConsumerKey:="Your consumer key", _
        ConsumerSecret:="Your consumer secret"
    Set TwitterClient.Authenticator = TwitterAuth

    ' Setup query request
    Dim Request As New WebRequest
    Request.Resource = "search/tweets.json"
    Request.Format = WebFormat.Json
    Request.Method = WebMethod.HttpGet
    Request.AddQuerystringParam "q", Query
    Request.AddQuerystringParam "lang", "en"
    Request.AddQuerystringParam "count", 20

    ' => GET https://api.twitter.com/1.1/search/tweets.json?q=...&lang=en&count=20
    '    Authorization Bearer Token... (received and added automatically via TwitterAuthenticator)

    Set QueryTwitter = TwitterClient.Execute(Request)
End Function
```

For more details, check out the [Wiki](https://github.com/VBA-tools/VBA-Web/wiki), [Docs](https://vba-tools.github.com/VBA-Web/docs/), and [Examples](https://github.com/VBA-tools/VBA-Web/tree/master/examples)

詳細については、[Wiki](https://github.com/VBA-tools/VBA-Web/wiki)、[Docs](https://vba-tools.github.com/VBA-Web/)をご覧ください。 [例](https://github.com/VBA-tools/VBA-Web/tree/master/examples)

### Release Notes

View the [changelog](https://github.com/VBA-tools/VBA-Web/blob/master/CHANGELOG.md) for release notes

リリースノートについては、[changelog](https://github.com/VBA-tools/VBA-Web/blob/master/CHANGELOG.md)をご覧ください

### About

- Author: Tim Hall
- License: MIT

---

具体的な使用感などは別の機会に。