# サーバーサイド SDK の概要

Stripe のサーバー側 SDK をインストールして使用する方法について説明します。

Stripe のサーバー側 SDK を使用すると、Stripe の REST API が使用されるため必要な作業量が削減されます。Stripe が管理しているる SDK は、Ruby、PHP、Java、Python、Node、.NET、Go で利用できます。[コミュニティライブラリ](https://docs.stripe.com/sdks/community.md)は、他のサーバー言語でも利用できます。

## インストールとセットアップ

以下の言語セレクターで言語を選択し、指示に従って SDK をインストールします。

#### Ruby

```bash
# Available as a gem
sudo gem install stripe
```

```ruby
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
```

インストールが完了したら、Stripe を初期化する必要があります。

#### Ruby

```ruby
require 'stripe'
Stripe.api_key = '<<YOUR_SECRET_KEY>>'
```

## API リクエストを送信する

Stripe API が使用されているオブジェクトは、主に作成、更新、削除、取得、一覧表示、検索の 6 つの方法で操作できます。次の例は、`Customer` オブジェクトを用いて 6 つの方法をそれぞれ説明しています。

#### 作成

John Doe という名前の顧客を作成します。

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=John Doe"
```

#### 更新

特定の ID を持つ顧客を取得します。

```curl
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "email=jdoe@example.com"
```

#### 削除

特定の ID を持つ顧客を削除します。

```curl
curl -X DELETE https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

#### 取得する

特定の ID を持つ顧客を取得します。

```curl
curl https://api.stripe.com/v1/customers/{{CUSTOMER_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

#### List

最近作成された 5 人の顧客をリストします。

```curl
curl -G https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d limit=5
```

#### 検索

Jane Doe という名前の顧客を検索します。

```curl
curl -G https://api.stripe.com/v1/customers/search \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "query=name:'Jane Doe'"
```

API リクエストには、さまざまなタイプのパラメーターを含めることができます。たとえば、`name` (文字列)、`address` (オブジェクト)、`preferred_locales` (リスト) を使用して顧客を作成する方法を次に示します。

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=John Doe" \
  -d "address[country]=US" \
  -d "address[city]=San Fransisco" \
  -d "preferred_locales[]=EN" \
  -d "preferred_locales[]=FR"
```

オブジェクトを更新するときに、そのプロパティの一部をクリアできます。動的な型付き言語の場合は、空の文字列を送信します。強力な型付き言語の場合は、特定の定数を使用します。たとえば、顧客の `name` (文字列) と `metadata` (キーと値のペアのハッシュ)を クリアする方法は次のとおりです。

#### Ruby

```ruby
customer = Stripe::Customer.update('{{CUSTOMER_ID}}', {
  name: '',
  metadata: '',
})
```

この例では、すべてのメタデータをクリアしますが、個々のキーをクリアすることもできます。メタデータの管理について詳しくは、[メタデータガイド](https://docs.stripe.com/metadata.md)をご覧ください。

## API レスポンスにアクセスする

API リクエストを行うたびに、Stripe から応答が返されます。

オブジェクトを作成、取得、または更新すると、オブジェクト自体が返されます。

```json
{
  "id": "pi_001",
  "object": "payment_intent",
  "amount": 1099,
  "currency": "usd",
  /* ... */
}
```

変数を使用して、そのオブジェクトのプロパティにアクセスします。

#### Ruby

```ruby
paymentIntent = Stripe::PaymentIntent.retrieve('{{PAYMENT_INTENT_ID}}')
puts paymentIntent.amount
```

オブジェクトを一覧表示または検索すると、要求されたオブジェクトと `data` 配列を含む `List` オブジェクトが返されます。

```json
{
  "object": "list",
  "data": [
    {
      "id": "pi_003",
      "object": "payment_intent",
      "amount": 4200,
      "currency": "usd",
      /* ... */
    },
    {
      "id": "pi_002",
      "object": "payment_intent",
      "amount": 2100,
      "currency": "usd",
      "payment_method_types": [ "link" ],
      /* ... */
    }
  ],
  "has_more": true,
  "url": "/v1/payment_intents"
}
```

`data` 配列でループを使用して、各オブジェクトのプロパティにアクセスします。

#### Ruby

```ruby
paymentIntentList = Stripe::PaymentIntent.list({ limit: 3 })
for pi in paymentIntentList.data do
  puts pi.amount
end
```

[自動ページ分割](https://docs.stripe.com/pagination.md#auto-pagination)を使用して、すべての結果を反復することもできます。

## レスポンスの拡張

一部のプロパティは展開可能または包含可能であり、`expand` パラメーターを使用して返すことができます。たとえば：

- PaymentIntent を取得し、関連付けられている PaymentMethod を展開します。
  ```curl
  curl -G https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}} \
    -u "<<YOUR_SECRET_KEY>>:" \
    -d "expand[]=payment_method"
  ```
- Checkout セッションを取得し、`line_items` プロパティを含めます。
  ```curl
  curl -G https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}} \
    -u "<<YOUR_SECRET_KEY>>:" \
    -d "expand[]=line_items"
  ```

詳しくは、[レスポンスの拡張](https://docs.stripe.com/expand.md)をご覧ください。

## リクエスト ID を取得する

各 API リクエストには、一意のリクエスト ID (`req_xxx`) が関連付けられます。これは、ダッシュボードでリクエストを調べ、Stripe が受け取ったパラメーターを確認したり、問題の解決が必要な場合に Stripe サポートと問題を共有するために使用されます。

ID は[ダッシュボードのログ](https://dashboard.stripe.com/test/workbench/logs)で確認するか、次のようなコードで直接確認できます。

#### Ruby

```ruby
customer = Stripe::Customer.create({ name: 'John Doe', })
puts customer.last_response.request_id
```

## 追加のリクエストオプションを設定する

API リクエストを送信するときに、追加のリクエストオプションを次のように設定できます。

- [特定の API バージョンを設定します](https://docs.stripe.com/sdks/set-version.md)。
- [連結アカウント](https://docs.stripe.com/connect/authentication.md)でリクエストを行います。
- [べき等キーを指定します](https://docs.stripe.com/api/idempotent_requests.md)。

## エラー処理

各サーバー SDK は、Stripe API からのエラー応答を例外タイプとして解釈するため、応答ステータスを自分で解析する必要はありません。各言語に適したエラー処理規則を使用して、これらのエラーを処理します。

#### Ruby

```ruby
begin
  Stripe::PaymentIntent.create(params)
rescue Stripe::CardError => e
  puts "A payment error occurred: #{e.error.message}"
rescue Stripe::InvalidRequestError => e
  puts "An invalid request occurred."
rescue Stripe::StripeError => e
  puts "Another problem occurred, maybe unrelated to Stripe."
else
  puts "No error."
end
```

詳しくは[エラー処理](https://docs.stripe.com/error-handling.md)をご覧ください。

## 文書化されていないパラメーターとフィールド

場合によっては、API リクエストのパラメータや API レスポンスのフィールドで、SDK で使用できないものに遭遇することがあります。これは、ドキュメント化されていない場合や、プレビュー中でプレビュー SDK を使用していない場合に発生する可能性があります。以下のガイダンスを使用して、これらのパラメータを送信するか、これらのフィールドにアクセスしてください。

### 文書化されていないパラメータを送信する

次の例では、文書化されていない boolean パラメータを使用して `Customer` を作成します。コード例では、SDK では公開されない `secret_feature_enabled` を使用しています。

#### Java

```java
CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("jenny.rosen@example.com")
    .putExtraParam("secret_feature_enabled", "true")
    .build();

client.customers().create(params);
```

### 文書化されていないフィールドにアクセスする

次の例では、`Customer` オブジェクトの文書化されていない boolean フィールドを読み取ります。コードサンプルでは、SDK では公開されない `secret_feature_enabled` を使用しています。

#### Java

```java
final Customer customer = client.customers().retrieve("cus_1234");
Boolean featureEnabled = customer.getRawJsonObject()
    .getAsJsonPrimitive("secret_feature_enabled")
    .getAsBoolean();
```

## ソースコード

各サーバー SDK のソースコードは、GitHub で入手できます。

| 言語         | リポジトリー                                                     |
| ---------- | ---------------------------------------------------------- |
| **Ruby**   | [`stripe-ruby`](https://github.com/stripe/stripe-ruby)     |
| **PHP**    | [`stripe-php`](https://github.com/stripe/stripe-php)       |
| **Java**   | [`stripe-Java`](https://github.com/stripe/stripe-java)     |
| **Node**   | [`stripe-node`](https://github.com/stripe/stripe-node)     |
| **Python** | [`stripe-python`](https://github.com/stripe/stripe-python) |
| **.NET**   | [`stripe-dotnet`](https://github.com/stripe/stripe-dotnet) |
| **Go**     | [`stripe-go`](https://github.com/stripe/stripe-go)         |

## StripeClient

`StripeClient` クラスは、リソースを検出し、Stripe API にリクエストするのに役立つエントリーポイントとして機能します。このパターンを、グローバル設定を使用していた以前のパターンよりも使用するメリットは次のとおりです。

- 異なる設定オプション (API キーなど) を持つ複数のクライアントを同時に使用できます。
- `StripeClient` は静的メソッドを使用しないため、テスト中に模擬テストが容易になります。
- 追加の API コール不要です。一部の言語では、更新や削除の前に取得処理が必要でしたが、`StripeClient` を使用することで、単一のメソッドコールですべての API エンドポイントにアクセスできます。

Node.js SDK には、常に同じパターンに従う `Stripe` クラスがあります。その他の言語については、次の SDK バージョンで新しいパターンが追加されました。従来のパターンを使用する古いバージョンのライブラリをターゲットとするコードと比較する場合、呼び出し方法が異なって表示される場合があります。

| 移行ガイド                                                                                                                             | StripeClient リリース |
| --------------------------------------------------------------------------------------------------------------------------------- | ----------------- |
| [Stripe-php 移行ガイド](https://github.com/stripe/stripe-php/wiki/Migration-to-StripeClient-and-services-in-7.33.0)                    | 7.33.0            |
| [Stripe-python 移行ガイド](https://github.com/stripe/stripe-python/wiki/Migration-guide-for-v8-\(StripeClient\))                       | 8.0.0             |
| [Stripe-java 移行ガイド](https://github.com/stripe/stripe-java/wiki/Migration-guide-for-v23#stripeclient)                              | 23.0.0            |
| [Stripe-ruby 移行ガイド](https://github.com/stripe/stripe-ruby/wiki/Migration-guide-for-v13)                                           | 13.0.0            |
| [stripe-dotnet マイグレーションガイド](https://github.com/stripe/stripe-dotnet/blob/master/CHANGELOG.md#stripeclient)                        | 46.0.0            |
| [Stripe-go 移行ガイド](https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client#migrating-from-global-configuration) | 82.1.0            |

## パブリックおよびプライベートプレビューバージョン

Stripe には、[パブリックプレビューフェーズ](https://docs.stripe.com/release-phases.md) とプライベートプレビューフェーズの機能があり、それぞれ [`beta`または `b` のサフィックス ](https://docs.stripe.com/sdks/versioning.md#public-preview-release-channel)] と [`アルファ`また`は`サフィックス ](https://docs.stripe.com/sdks/versioning.md#private-preview-release-channel)] の付いた SDK のバージョンからアクセスできます。